aardio 文档

win.form 使用指南 - 创建窗口并添加控件

一. 窗体设计器 #

在 aardio 中创建窗口有以下方法：

默认将在窗体设计器中以"设计视图"打开窗体，
我们可以在开发环境左下方的"界面控件"选择和拖放控件到窗体上。
点击窗体或控件，在右侧属性面板可以设置控件的属性。

我们可以点击"代码视图"切换到代码编辑器模式，也可以直接按相同的 Ctrl+U 快捷键来回切换视图模式。在窗体设计器上直接双击控件也可以切换到代码模式并且为控件添加事件函数（默认会添加 oncommand 事件，不同的控件有所不同 ）。

二. 窗体设计器生成的代码结构 #

我们创建窗口，添加一个按钮与一个文本框，切换到代码模式，我们看到生成了以下代码：

import win.ui;
/*DSG{{*/
var winform = win.form({ text="窗口标题";right=759;bottom=469 })
winform.add({
button1={cls="button";text="Button";left=550;top=414;right=701;bottom=458;z=1};
edit1={cls="edit";text="Edit";left=22;top=16;right=735;bottom=398;edge=1;multiline=1;z=2}
})
/*}}*/

winform.show();
win.loopMessage();

/*DSG{{*/ 到 /*}}*/ 之间的代码由窗体设计器自动生成，这部分代码默认会折叠并显示为『窗体设计器生成代码(请勿修改)』，通常直接修改这部分代码是不必要的，应当通过窗体设计器修改相关属性。

同一个代码文件不应当包含多个 /*DSG{{*/ ... /*}}*/ 代码块。建议使用不同的代码文件创建不同的窗口，请参考: 创建多窗口程序 。

注意：win.form 类并不在 win.ui 名字空间下面，但必须使用 win.ui 库导入 win.form 类。这在 aardio 标准库中是一个特例，其他标准库导入的类或者名字空间与库路径会保持一致，例如 web.view 库会导入 web.view 类。

三. 调用 win.form 类创建窗体对象 #

原型：

var winform = win.form(formPropertiesTable)

说明：

参数 formPropertiesTable 是一个表对象。
formPropertiesTable 包含的键值对定义窗口的属性。
实际上 formPropertiesTable 就是我们在窗体设计器上设置的窗体属性认集合。

win.form 返回 winform 对象，在 aardio 中一般窗体通常默认命名为 winform,只有程序的第一个主窗口会命名为全局变量 mainForm。

在 aardio 的文档一般会用 winform 泛指所有 win.form 创建的窗体对象。

示例：

var winform = win.form({ text="窗口标题";right=759;bottom=469 })

在 aardio 中如果函数参数是一个表对象的构造器，
并且第一个出现的元素是用等号分隔的名值对，则可以省略外层的括号，
例如上面的代码可以简写为：

var winform = win.form( text="窗口标题";right=759;bottom=469 )

注意上面这种写法是构造了一个表对象作为参数，不是命名参数（ aardio 里没有命名参数 ）。

win.form 的构造参数表里不指定 left,top 坐标时则使用默认值 -1，这会让窗口显示在屏幕居中的默认位置。这时候窗口的宽度与高度分别为 right ＋ １,bottom ＋ １。如果 left,top 为小于等于 -2 的值则表示以窗口显示在屏幕右下角以后取得的左上角坐标作为原点计数。如果 left,top 为大于等于 0 的值则表示自屏幕左上角正常计数。如果 right, botom 字段也省略，则会自动指定一个默认值。

text 字段则指定了窗口标题，如果不指定 text 则会自动指定 title 字段为 false，这会使窗口不显示标题栏也就无法使用标题栏的最大化、最小化、关系这些常用按钮。只要是需要显示的窗口建议总是指定 text 字段，即使不显示标题栏的无边框窗口也应当指定窗口标题（方便在系统任务栏查看标题）。

四. 调用 winform.add 函数添加控件 #

1. 函数原型：

winform.add = function(controlsPropertiesTable) {
    /*
    controlsPropertiesTable 参数是一个表。
    这个表包含了定义一个或多个控件的名值对: 键名为为控件的名称，名字对应的值则是控件初始化属性集合。 
    */
}

2. 参数说明：

controlsPropertiesTable 参数是一个表对象。 controlsPropertiesTable 包含的键值对定义了一个或多个控件： 键名为该控件的名称，键名对应的值刚是描述每个控件初始化属性的集合（也是一个表对象）。

这些控件的初始化属性可以在窗体设计器里在设计时修改，所以又称为【控件设计时属性】，与控件对象创建成功后可在运行时访问的【控件运行时属性】相区别。

3. 使用示例：

import win.ui; 
var winform = win.form({ text="窗口标题";right=759;bottom=469;bgcolor=0xFFFFFF });

winform.add({
    button1={//指定访问名称为  winform.button1
        cls="button";//指定用 win.ui.ctrl.button 类构造控件
        text="添加第一个按钮 button1 到  winform.button1";//控件显示的标题
        left=264;top=410;right=469;bottom=454;//控件位置
        z=1 //Z 序
    };
    button2={//指定访问名称为  winform.button2
        cls="button";//指定用 win.ui.ctrl.button 类构造控件
        text="添加第二个按钮 button2 到 winform.button2";//控件显示的标题
        left=499;top=410;right=688;bottom=454;//控件位置
        z=2 //Z 序
    };
    edit1={//指定访问名称为  winform.edit1
        cls="edit";//指定用 win.ui.ctrl.edit 类构造控件
        text="添加第一个编辑框 edit1 到  winform.edit1";//控件文本
        left=386;top=16;right=739;bottom=398;
        edge=true;multiline=true;z=3 //边框，多行，Z 序
    };
    edit2={//指定访问名称为  winform.edit2
        cls="edit";//指定用 win.ui.ctrl.edit 类构造控件
        text="添加第一个编辑框 edit2  到  winform.button2";//控件文本
        left=22;top=16;right=375;bottom=398;//控件位置
        edge=true;multiline=true;z=4 //边框，多行，Z 序
    }
});

上面的代码创建了 4 个控件：

controlsPropertiesTable 里的控件名称也就是添加到 winform 对象的成员名字，例如控件名为 "button1" ，则之后的代码就要通过 winform.button1 访问该控件。

可以在窗体设计器视图中设计好控件的初始化属性，然后切换到代码视图就可以查看细节。控件的很多设计时属性与运行时属性是相同的，但有些设计时属性仅在控件初始化参数中有效，例如 plus 控件只有在设计时属性中才会使用 bgcolor,forecolor 这些 GDI 格式的颜色值，运行时则由 background, foreground 这些运行时属性支持 0xAARRGGBB （ AA 的值越小，颜色透明度越大）这种 GDI+ 格式的颜色值。

这里介绍几个常用的控件设计时属性：

4. winform.add 函数的返回值：

虽然 winform.add 有返回值，但是我们通常不使用 winform.add 函数的返回值。

winform.add 的返回值与传入参数的结构相同，如果传入的是 controlsPropertiesTable 则返回的与是包含控件名值对的表，只不过对应控件名字的值变成了创建好的控件对象。

应当通过 winform 上的控件名称去访问控件，例如 winform.button1，winform.edit1 ，这样对开发环境更友好，可以获得更好的智能提示与代码补全帮助。

五. 创建窗口的高级用法与隐藏参数

win.form 构造参数与 winform.add 有一些不常见的用法与隐藏参数，用于解决一些不太常见的需求。关于这些参数在 aardio 自带的"范例 » Windowns 窗口 » 基础知识" 内有详细的演示与注释说明，也可以查看库参考手册，作为入门指南这里不多讲。

范例：

六. 创建窗口示例 #

//自 win.ui 库中导入 win.form 窗口类
import win.ui;

/*DSG{{*/

//创建窗口
var winform = win.form(text="窗口标题不要省略";right=763;bottom=425)

//创建多个控件应当仅调用 winform.add 一次
winform.add({//如果函数的参数只有一个表对象，可省略名值对外层的 {}  。

    //指定访问控件的名字为 winform.button1 ，不可省略
    button1={
        cls="button";// 指定用类 win.ui.ctrl.button 创建按钮控件，不可省略
        text="点击我";// 按钮上的文字
        left=556;top=367;// 按钮左上角坐标
        right=689;bottom=407; // 按钮右下角坐标
        z=1 // 文本框左上角坐标
    };

    //指定访问控件的名字为 winform.edit1 ，不可省略
    edit1={
        cls="edit";// 指定用类 win.ui.ctrl.edit 创建文本框控件，不可省略
        text="输入文本";// 文本框内的文字
        left=9;top=10;// 文本框左上角坐标
        right=752;bottom=351;// 文本框右下角坐标
        multiline=1;//多行文本框
        z=2 //Z序，可省略
    }
})

/*}}*/

// 设置按钮的点击事件处理程序，winform.button1 也就是 winform.add 的参数中创建的名为 "button1" 的控件。
winform.button1.oncommand = function(id, event) {
    // 从 1 循环到 10 的数字输出到 edit 控件
    for(i=1; 10; 1) {
        //注意 edit 以 '\r\n' 换行，而 richedit 以 '\n' 换行
        winform.edit1.appendText(i,'\r\n'); //winform..edit1 也就是 winform.add 的参数中创建的名为 ".edit1" 的控件。
    }
};

//显示窗口
winform.show();

//启动界面线程消息循环
win.loopMessage();

这个代码示例首先自 win.ui 库导入了 win.form 类，然后创建了一个带有指定标题的 winform 窗口。接着，它在该窗口上添加了一个按钮和一个文本框。当按钮被点击时，会从 1 循环到 10 的数字，每个数字后跟一个换行符，然后输出到文本框中。最后，显示窗口并进入消息循环，以便响应用户的操作。

用户在点击按钮时会回调 winform.button1.oncommand 事件函数，请参考 aardio 范例：响应控件命令

七. 事件处理：命令、通知、消息回调

另外，不同的控件也定义了不同的事件，例如定义了 onSelChanged，等事件。而 plus 控件则通过标准库 win.ui.tracker 支持 "onMouse" 前缀的一系列鼠标事件。

八. 自定义控件与扩展控件

1. 自定义控件

在窗体设计器上拖放一个自定义控件（ custom 控件 ），然后可以在 IDE 右侧的窗体属性面板中修改控件类名。

custom 控件的类名可以修改为两种类型的值：

请参考 自定义控件使用指南

2. 扩展控件

以添加到 custom, static 的控件窗口作为宿主窗口，使用其他类库扩展功能。

下面是使用 web.view 库扩展 static 控件使其显示 Lottie 的例子：

import win.ui;
/*DSG{{*/
var winform = win.form(text="Lottie 动画";right=757;bottom=467;bgcolor=0xFFFFFF)
winform.add(
static={cls="static";left=42;top=42;right=451;bottom=273;bgcolor=0xFFFFFF;z=1}
)
/*}}*/

import web.form;
var wb = web.form(winform.static);

wb.html = /**
<!doctype html>
<html>
<head> 
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <style>html,body{ height:100%; margin:0; overflow:hidden } </style> 
    <script src="https://lib.baomitu.com/lottie-web/5.10.0/lottie.min.js"></script> 
</head><body><script>
lottie.loadAnimation({
    container: document.body,
    renderer: 'svg',
    loop: true,
    autoplay: true,
    path: "https://download.aardio.com/demo/lottie/1.json" 
});
</script>
**/

winform.show();
win.loopMessage();

web.view 基于强大的 WebView2 浏览器控件。如果较为简单的网页也可以使用 web.form，基于更轻量的进程内 COM 控件,但 web.form 仅支持兼容 IE 的网页。

传统控件的样式较为简单。用 aardio 提供的 plus 控件则可以代替很多传统控件的功能，并且可以使用 siin 函数更方便的配置更好看的外观样式。如果需要更丰富的外观定义功能，则可以使用 web.view 等浏览器组件扩展 custom, static 等控件窗口使其支持加载并显示网页，在 aardio 中网页中的 JavaScript 与本地 aardio 代码交互非常方便。

九. 无边框窗口 #

win.form 的构造参数可使用 border 字段指定边框，示例：

var winform = win.form(text="创建无边框（无标题栏）窗口";border="none")

border 可指定的值如下：

创建无边框窗口的目的通常是为了自己定制标题栏与边框，aardio 提供了一个简单的示例库 win.ui.simpleWindow 。

用法演示：

import win.ui;

//创建无边框（无标题栏）窗口，省略了宽高与位置参数并使用默认值
var winform = win.form(text="aardio form";border="none";bgcolor=0xFFFFFF)

//添加深色的标题栏背景（ bk 是仅用作背景绘图的无句柄窗口）, marginRight 字段指定控件的右边距为 0 以代替固定的 right 字段值。
winform.add(
    bk={cls="bk";bgcolor=0xA4A0A0;left=0;top=0;bottom=32;marginRight=0;dl=1;dr=1;dt=1;z=1}
)

//添加阴影边框、标题栏等，默认为透背背景，标题栏上最大化、最小化、关闭按钮等默认字体为白色
import win.ui.simpleWindow;
win.ui.simpleWindow(winform);

winform.show();
win.loopMessage();

win.ui.simpleWindow 创建了一个简洁美观的标题栏，并创建了最大化、最小化、关闭窗口的按钮，按住标题栏可能拖动。同时也会在窗体周围创建阴影边框，支持拖动窗口边框改变窗体大小。默认情况下 win.ui.simpleWindow 创建的标题栏背景是透明的，标题栏按钮默设也是透明背景与白色字体。我们可以用 bk 或 bkplus 控件绘制深色的标题栏背景。bk 或 bkplus 控件并不会创建窗口，只是在父窗体上绘图，所以性能较好，也更适合在上面重叠放置其他控件。

也可以通过 win.ui.simpleWindow 对象自定义标题栏按钮配色，示例：

import win.ui;
var winform = win.form(text="aardio form";border="none";bgcolor=0xFFFFFF)

import win.ui.simpleWindow;
var sw = win.ui.simpleWindow(winform);

//标题栏按钮都是 plus 控件，skin 函数用法与 plus 控件相同，颜色使用 GDI+( 0xAARRGGBB ) 格式的值。
sw.skin(
    background = { 
        hover = 0x44B0C4DE; 
        active = 0x664682B4; 
        default = 0x00FFFFFF; 
    }
    color = { 
        hover = 0xFF191970;
        active = 0xFFFFFFFF; 
        default = 0xFF2F4F4F; 
    }
)

winform.show();
win.loopMessage();

无边框窗口都应当添加自定义的标题栏和边框，最简单的方法就是直接使用标准库写好的 win.ui.simpleWindow。

请参考：

Markdown 格式