global 库模块帮助文档

global 成员列表 #

全局名字空间
global.x 等价于 ..x
.

_AARDIO_VERSION #

aardio 内核版本号

_ARGV #

解析后的进程启动参数表，已解析双引号、命令行参数转义符等并转换为数组,
命令行解析规则请参考标准库中 string.cmdline 的源码,

ARGV 既包含命令行参数数组,也包含按下列规则解析的键值对:
以斜杠或短横线开始的前导参数作为键(键名移除一个或多个相同的前导字符,区分大小写)，
如果前导参数包含等号,则以等号拆分为键值对,等号前后不应有空格,
否则检查下一参数如果没有相同的首字符则设为此键对应的值，
如果一个前导参数没有指定值,则默认值为空字符串（逻辑值为true）

_ARGV仅在发布后的进程启动线程中存在,开发环境中 _ARGV 为空表。
非主线程请改用 thread.cmdline

_CMDLINE #

命令行参数的原始文本
也可以使用 _ARGV 获取解析后的命令行参数
_CMDLINE 仅在启动线程中存在,一般用于main.aardio,开发环境中为null
可使用#操作符检测参数是否为空

_HAPPICON #

应用程序图标句柄，可在工程属性中自定义该图标，
图标在不再使用时会自动释放,不要手动释放该图标
_HAPPICON仅在启动线程中存在

_HINSTANSE #

当前应用程序的实例句柄

_IMPORTURL #

用于注册远程扩展库安装网址的表,
可添加新的键值，键为库名称，值为库安装文件网址,
网址可指定 *.tar.lzma 格式安装包或 *.aardio 格式库文件"
必须写在引用扩展库的语句之前

_INVALID_HANDLE_VALUE #

topointer(-1)
表示无效句柄

_STUDIO_INVOKED #

检测程序是否在 aardio 开发环境内运行。

可能的值如下：

• 值为 "process": aardio 程序是在开发环境内以独立的进程模式运行。

• 值为 "thread": aardio 程序是在开发环境主进程内以线程模式运行。

└── 在开发环境内启动并且首个 import 语句导入的是 ide 库即以线程模式运行。

└── 为保持开发环境的稳定与独立性，任何时候都不建议使用线程模式。

• 值为 "external": 外部程序在非主线程内将开发环境设为应用根目录，并且导入了 ide 库。
  

└── 此模式可启用自动安装扩展库等功能。

• 值为 null : 表明 aardio 程序不是由开发环境启动，并且未在非主线程导入 ide 库。

_WIN10_LATER #

当前系统是否为WIN10/Win2016或之后的版本

_WIN7_LATER #

当前系统是否为WIN7/Win2008 R2或之后的版本

_WINE #

如果程序在 Linux(Wine、CrossOver) 环境下运行此常量包含wine版本号
否则为 null

_WINXP #

当前系统是否为WINXP或Win2003
否则为Vista/WIN2008或以后的版本

_WIN_64 #

_WIN_64 = 当前系统是否为64位

_WIN_VER_BUILD #

Windows 构建版本号
Windows10 构建版本号与发行版本号的对应关系请参考 win.versionEx

_WIN_VER_MAJOR #

Windows 主版本号

_WIN_VER_MINOR #

Windows 副版本号

_struct_aligned #

用于结构体中自定义对齐
指定为1按按照实际字节数对齐

assert() #

断言函数
第一个参数为真则返回此参数
否则将第二个参数作为异常抛出

assert2(2,) #

断言函数
参数 @2 为真则返回其他值,否则抛出异常
参数 @1 指定抛出异常的调用级别,2 为调用者,1 为当前代码

assertf() #

反断言函数
第一个参数为假则返回第二个参数)
否则将第二个参数作为异常抛出

beforeSystemEndSesssion #

..subscribe("beforeSystemEndSesssion",function(){  
    /*即将关机执行此回调，不可执行耗时操作*/  
} );

beforeUnload #

..subscribe("beforeUnload",function(){  
    /*进程的启动线程退出前执行此回调非。  
启动线程可用 table.gc 注册析构函数。*/  
} );

call(函数,owner,其他调用参数...) #

调用函数,可自定义owner对象,
参数@1可以是类、函数等可调用的对象,
即使是不可调用类型或者null值也不会抛出异常,
可以有任意个其他调用参数

成功首个返回值true,其他返回值为被调用函数返回值,
失败返回 false,错误信息

callex(错误处理函数,调用函数,owner,其他参数) #

调用函数,可自定义owner对象,
不指定错误处理函数时调用默认错误处理函数,可触发global.onError,
返回值一表示调用是否成功,其他返回值为函数返回值
失败返回false,错误信息

collectgarbage(."collect") #

运行完整的垃圾回收

collectgarbage(."count") #

查询内存占用(Kb)

collectgarbage(."restart") #

重启垃圾收集器

collectgarbage(."setpause") #

垃圾收集暂停时间值
第二参数除以100代表内存回收前要等多久，
默认值为200，指定内存达到上一个周期结束时的两倍时进入下一个周期，
函数返回原来的设置值

collectgarbage(."setstepmul") #

设置垃圾收集器步长倍增器的值
第二参数除以100代表单步的速度，
默认值为200，也即内存分配速度的两倍
函数返回原来的设置值

collectgarbage(."step",1) #

进行一次垃圾回收迭代,
参数2越大，执行的次数越多，执行时间越久,
如果已经是最后一次迭代返回true

collectgarbage(."stop") #

禁用垃圾收集器

dumpcode() #

将函数输出为字节码,
参数一可以是aardio代码，aardio源文件路径，或函数对象,
可选用参数@2自定义代码块名称
可选用参数@3指定是否移除调试信息

error #

抛出一个异常。

如果库函数报错，也可以临时增加代码检查异常参数，
并使用 error 函数向指定的调用级别抛出异常，以辅助定位错误的调用代码

禁止在 catch 语句内部调用 error 函数（ global.onError 更方便 ）

如果发布程序禁用调试信息则 error 输出的信息会被精简。
而 errput 输出的错误信息会被保留（调用栈信息仍会被精简）

error(错误信息,调用级别) #

抛出一个异常。

可选用参数 @2 指定抛出异常的调用级别，
1 为自身，2 为上层调用者，依次上推……

如果库函数报错，也可以临时增加代码检查异常参数，
并使用 error 函数向指定的调用级别抛出异常，以辅助定位错误的调用代码

errput #

输出错误信息，但不会抛出异常。

errput(错误信息,错误标题) #

输出错误信息。
如果参数@1为空则忽略不执行任何操作，参数 @2 可省略。
此函数会首先触发默认错误处理程序，
如果错误处理程序或 onError 返回 null 则不输出错误信息。

error 函数会中断执行并抛出异常，直到异常被捕获。
errput 则不会抛出异常，错误信息输出以后程序会继续向后执行。

如果发布程序禁用调试信息则 error 输出的信息会被精简。
而 errput 输出的错误信息会被保留（调用栈信息仍会被精简）

eval("字符串参数") #

将字符串转换为代码执行,并返回一个或多个值
失败抛出异常
注意，如果是开发网站或服务端，
应避免用户提交的字符串可以在eval中执行,
服务端到客户端传输数据时不应使用eval实现序列化
因为eval可以执行任意的代码
服务端到客户端间序列化数据，应当改用普通的数据解析器,例如json

execute("字符串参数") #

调用系统命令行,成功返回 0，此函数会打开命令行窗口。
以下库或函数提供类似且更强大的功能：
raw.execute,
process,
process.execute,
process.popen,
process.popen.cmd 专用于启动命令行,
process.popen.cmd64 专用于启动 64 位命令行,
process.popen.ps,
process.wow64.execute 专用于启动 64 位程序,
console.pause

for_in #

for(k,v in /*  
指定函数对象则作为迭代器循环调用直到返回 null 。  
指定函数调用语句则必须返回函数对象（作为循环执行的迭代器）。  
指定表对象（或数组）则遍历该表返回表示键值的循环变量 k,v 。  
如果在这里指定表：  
- 在迭代中只能修改表的键值，不可增加新键（可能打乱迭代次序）  
- 迭代表对象的非数组成员时不保证遍历顺序。  
- 排序遍历表中的名值对请调用 table.eachValue 创建迭代器。  
- 顺序遍历数组或类数组可调用 table.eachIndex 创建迭代器。  
- 改用计数 for 循环遍历数组则能保持索引顺序。*/){  

}

gcdata(元表) #

..gcdata(    
    _topointer =  /*pointer指针*/   
    _gc = function(){  

    }   
)

invoke(调用函数,owner,其他调用参数...) #

调用函数,可自定义被调用函数的owner参数,
返回值为函数返回值,失败则直接抛出异常
可添加任意个数的调用参数

这个函数的参数用法与 call 函数完全相同，
但 invoke 只有修改 owner 的作用，不会捕获异常，
也不会改变函数的返回值

lambda #

lambda (/*lambda定义一个匿名函数，  
用于接收输入参数并返回一个表达式，  
不能使用表达式以外的其他语句或语句块，  
不能返回多个值*/)

lambdaλ #

λ (/*lambda定义一个匿名函数，  
用于接收输入参数并返回一个表达式，  
不能使用表达式以外的其他语句或语句块，  
不能返回多个值*/)

lasterr(err) #

返回WINAPI或COM API的最后一次错误信息,第二个返回值为错误码
无错误则返回null空值,
可选使用参数 @err 自定义错误代码

loadcode() #

编译aardio代码并返回函数对象,失败返回null以及错误信息,
参数可以是aardio文件,或者aardio代码,或者指定的loader函数
可选使用参数@2自定义代码块名称

注意使用相对路径时的参考目录必须是应用程序根目录,并以斜杠作为路径首字符
参数不应使用参考当前目录的路径,因为当前目录是可变的,
可自工程中拖动文件到代码中生成正确路径

loadcodex #

加载并运行aardio文件或代码
注意使用相对路径时的参考目录必须是应用程序根目录,并以斜杠作为路径首字符
参数不应使用参考当前目录的路径,因为当前目录是可变的,
可自工程中拖动文件到代码中生成正确路径

loadcodex(aardio代码,...) #

加载并运行aardio文件或代码,可指定多个调用参数,
被调用文件可在开始处使用 ... 操作接收多个参数
返回值为被调用文件的返回值

loadcodex(函数,...) #

运行函数,可指定多个调用参数
返回值为被调用函数的返回值

messageGet(msg) #

等待并获取窗口消息,
msg参数可以是MSG结构体，也可以是一个空表用于接收新的MSG结构体,也可以省略
成功返回已填充消息的MSG结构体（如果指定了msg参数则该参数就是此返回值),
失败返回false,程序退出返回null

messagePeek(msg,窗口句柄,最小消息,最大消息,选项) #

检查并获取窗口消息,
msg参数可以是MSG结构体，也可以是一个空表用于接收新的MSG结构体,也可以省略
成功返回已填充消息的MSG结构体（如果指定了msg参数则该参数就是此返回值),
无消息返回false,程序退出返回null

所有参数都是可选参数
选项不指定则默认为 _PM_REMOVE 表示自消息队列移除该消息
其他选项请参考同名WINAPI的说明

messageTranslateDispatch(msg) #

分发处理窗口消息,
参数为消息对象.

namespace #

namespace /*指定名字空间路径，打开存在的名字空间或创建新名字空间。  
namespace 语句不会触发名字空间的元方法（with 语句则相反）。  
注意 .NET 名字空间依赖元方法自动导入下级名字空间。  

名字空间作用域为当前函数体（以及内部函数），单个代码文件属于匿名函数。  
namespace 语句块必须执行完成（没有中途跳出）才能恢复原名字空间。  
如果当前文件不需要恢复名字空间，可省略后面的语句块。*/{  
    //在名空空间内应使用 .. 操作符访问外部全局名字空间下面的对象  

}

onError(错误信息,是否已退出退用栈) #

//此函数应在主线程中定义并自动注册到子线程，应遵守线程函数规则  
global.onError = function( err,over ){   
    if(!over){  
        import debug;  
        var stack = debug.traceback(,"调用栈",3);  
    }  

    if( _STUDIO_INVOKED ) return err;/*IDE中返回错误信息以继续显示*/   
}

print #

aardio 代码在解析模板语法时，将自动调用此函数输出数据。
在不同类型的应用中，print 可能指向不同的输出函数。
例如在 HTTP 服务端中 print 将自动指向 response.write 函数。
而在调用 string.loadcode 时 print 将临时指向拼接字符串的代码。

用户不应随意改动 print 函数的指向，应交由负责模板输出的库或框架自动管理,
也不应将 print 赋值到其他变量后再进行调用，因为 print 函数随时可能被改变指向。
用户应当调用确定的 response.write，console.log 等函数而不是可变的 print 函数。

在未调用重写 print 函数的库或函数的默认情况下：
如果在开发环境中且首次调用模板或 print 输出的是 HTML 代码，则创建网页控件并显示 HTML，
否则 print 函数将默认调用 io.print 函数向控制台窗口输出内容。
print 在默认调用 io.print 前会自动打开控制台，之后在退出非界面线程前会暂停控制台。

print(...) #

aardio 代码在解析模板语法时，将自动调用此函数输出数据。
支持多个不定参数，每个参数都会自动调用 tostring 转换为字符串。
此函数可能实际指向不同的输出函数。

publish("字符串参数",) #

在当前线程内发布消息,
运行当前线程所有所有通过调用 subscribe 函数订阅此消息的函数,
可添加任意个触发参数

reduce(数组,回调函数,初始值) #

reduce(/*从左到右遍历数组中的值并应用回调函数归约运算为单个值。  
prev 参数数为上次调用返回的值或初始值。  
无初始值则取首个成员值为初始值，并自第2个成员开始遍历。  
next 参数为下一个成员值，index 参数为下一个成员索引。  
arr 参数为正在遍历的数组，arr 与 owner 参数指向同一对象。*/,function(prev,next,index,arr){  
    return prev + next  
})

rget(函数或起始位置,) #

参数@2通常使用一个函数调用并可能返回多个值,
参数@1指定截取返回值的起始位置,可使用负数表示尾部倒计数

setlocale(."all") #

返回当前区域设置

setlocale(."all","chs") #

简体中文语言区域设置
返回区域设置全称

setlocale(."all","enu") #

英文语言区域设置
返回区域设置全称

setlocale(."all","字符串参数") #

修改当前区域设置为默认设置
返回区域设置全称

setlocale(."collate","字符串参数") #

设置 string.collate 函数比较文本时使用的本地化区域,
返回区域设置全称,仅获取设置可省略参数 @2

setlocale(."ctype","字符串参数" ) #

设置当前程序字符类别及转换使用的本地化区域,
返回区域设置全称,仅获取设置可省略参数 @2

setlocale(."monetary","字符串参数" ) #

设置当前程序金融货币使用的本地化区域,
返回区域设置全称,仅获取设置可省略参数 @2

setlocale(."numeric","字符串参数" ) #

设置当前程序使用的数值本地化区域，影响默认小数点，
主要影响的是 tonumber 与 tostring 等数值与文本转换函数，
不会影响 aardio 语法解析中的小数点（总是句点）。

汉语和多数英语环境小数点默认为句点,多数欧洲国家小数点默认为逗号,
返回区域设置全称,仅获取设置可省略参数 @2

setlocale(."time","chs") #

设置时间日期格式使用简体中文语言区域区域,
返回区域设置全称,仅获取设置可省略参数 @2

setlocale(."time","enu") #

设置时间日期格式使用英文语言区域,
返回区域设置全称

setlocale(."time","字符串参数" ) #

设置当前程序时间日期格式使用的本地化区域,
返回区域设置全称,仅获取设置可省略参数 @2

setprivilege('SeDebugPrivilege',true) #

设置指定进程权限
成功返回true,失败返回false

sleep(毫秒) #

延时（CPU 休眠.）
此函数返回值总是为 true。
提升 sleep 函数计时精度请使用 time.period 或改用 time.performance.delay。

sleep 函数会卡界面并影响其他依赖消息处理的功能。
界面线程请改用 thread.delay 函数。
界面线程请改用 thread.delay 函数。
界面线程请改用 thread.delay 函数。

subscribe() #

返回对象:SubscriberObject

subscribe(订阅消息名,触发函数,是否前置) #

subscribe("/*要订阅的消息名称, 请使用 publish 函数触发此消息。  
调用 subscribe 函数返回对象的 remove 成员函数可撤消本次订阅。  
在订阅触发函数中返回 false 也可以撤消所属订阅。  

如果在触发函数中可能使用已关闭的窗口对象，  
应当先检查窗口的 valid 属性判断窗口是否有效。  
对于这类窗口改用 thread.command 更合适*/",function(...){  

} )

switch(selector,caseTable,default,...) #

switch(/*@selector 参数指定任意索引值。    
@caseTable 参数必须指定一个待检索的表对象（不能是其他数据类型）。    
@default 参数可省略或指定一个代替 @caseTable.default 的函数对象。    

使用 @selector 作为索引获取 @caseTable 表对应的成员函数并执行，    
如果没有找到函数则执行 @default 或 caseTable.default 指定的默认函数。    
如果没有匹配到任何函数或默认函数则忽略不执行任何操作。    

@default 参数后面的所有参数依序转发给被调用函数。    
调用的所有返回值由 switch 函数原序转发给调用方。*/,{    
    case1: function(){  

    };  
    case2: function(){  

    };   
    case3: function(){  

    };    
    default: function(){  

    };   
})

tonumber #

转换参数并返回数值,不修改输入参数,失败返回 null
转换成功会返回多个值，将返回值放入圆括号可转换为单个值。

在数值运算，以及 math 函数库除有特别说明以外都支持字符串参数自动转数值。
其他函数的数值参数如用于上述数值运算，同样支持字符串自动转数值。
原生 API 函数，COM 函数则应当明确区分字符串与数值

tonumber(值) #

转换参数并返回数值,
如果参数@1是指针类型变量转换为内存地址,
如果参数@1是布尔值,false转为0,true转为1
如果参数是字符串或buffer类型,转换成功返回数值以及转换的字符串长度,
其他对象尝试调用_tonumber元方法转换为数值
转换失败返回null

tonumber(字符串,进制,开始位置,默认小数点) #

强制转换字符串为数值类型,自动识别进制,
忽略首尾空白字符,空白字符串返回 null,
注意空白字符串在算式或等式中会自动转换为 0 而不是 null,

参数@1可以是字符串或buffer类型,
可选用参数@2指定进制，可选用参数@3指定开始位置
参数@4可选用表示字节码的数值自定义小数点，
不指定使用当前区域默认小数点：
汉语和多数英语环境小数点默认为句点,多数欧洲国家小数点默认为逗号,
可调用 setlocale("numeric") 修改默认区域,
请注意:即使指定了小数点,区域默认小数点仍然是有效的。

转换成功返回数值,以及转换为数值的字符串长度
转换失败返回null

topointer #

转换参数并返回指针,不修改输入参数

topointer(内存地址) #

转换数值参数并返回指针，不修改输入参数。
参数 @1 为 0 或 null 时返回 null，忽略其他参数。
topointer(0) 是多余无意义的写法，请直接写 null 。

此函数仅作类型转换,不能提取对象内部指针
提取指针应使用raw.toPointer函数

topointer(指针,偏移值) #

指针必须是 pointer 类型指针, 参数@1 为 null 时返回 null 。
偏移值以字节为单位，可以为负数。

此函数仅作类型转换，不能提取对象内部指针。
提取指针应使用 raw.toPointer函数

tostring #

转换参数@1指定的值为字符串类型,不修改输入参数,

tostring(number,radix,decPoint) #

转换 @number 指定的数值为字符串。
可选用参数@2指定进制,指定16进制添加0x前缀,其他进制无前缀。

参数 @decPoint 可选用表示字节码的数值指定小数点，
不指定则使用当前区域默认小数点:
汉语和多数英语环境使用句点,多数欧洲国家使用逗号。
可调用 setlocale("numeric") 修改区域以改变默认小数点

tostring(time,format,locale) #

转换 @time 指定的时间对象为字符串。
可选用 @format 自定义时间格式化串，参数 time 对象文档，
可选用 @locale 指定格式化区域，用法与 setlocale 参数@2相同,
例如简体中文为 "chs" 英语为 "enu"

tostring(value,...) #

转换参数@1指定的值为字符串类型,不修改输入参数。

如果对象指定了 _tostring 元方法则调用该元方法返回值,
tostring 第二个参数开始会传递为 _tostring 元方法的参数

try_catch #

try{  
    /*注意只有 return 语句可以退出 try 或 catch 语句。  
不能访问此语句外部的 ... 参数，可提前用 {...} 转换为数组。*/  
}  
catch (e){  

}

with #

with /*请指定要设为当前名字空间的表达式。  
with语句将对象临时绑定到当前名字空间，执行结束释放绑定。  
名字空间作用域为当前函数体（以及内部函数），单个代码文件属于匿名函数。  
with 语句必须执行完成（没有中途跳出）才能恢复当前函数名字空间。*/{  
    //在名空空间内应使用 .. 操作符访问外部全局名字空间下面的对象  

}

::Kernel32 成员列表 #

::Kernel32.* #

可不用声明直接在此输入函数名并调用API函数

一、传入参数规则：
1、null参数不可省略
2、32位整数类型，小于32位的整数、以及枚举类型都可以直接在API参数中写数值。
3、对于任何数值类型的指针（输出参数）一律使用结构体表示，例如double * v 表示为{ double v }
4、数组使用结构体表示
5、所有结构体传给API的都是指针地址，都是输出参数并增加返回值

二、返回值规则：
1、返回值默认为int类型,可用 >>> 0 强制转为无符号数,
2、可以使用[API尾标]改变返回值为其他类型

三、所有可用的【API尾标】:
::Kernel32.ApiNameW() 切换到Unicode版本，字符串UTF8-UTF16双向转换
::Kernel32.ApiNameA() 切换到ANSI版本,字符串不作任何转换
::Kernel32.ApiNameL() 返回值为64位LONG类型
::Kernel32.ApiNameP() 返回值为指针类型
::Kernel32.ApiNameD() 返回值为double浮点数
::Kernel32.ApiNameF() 返回值为float浮点数
::Kernel32.ApiNameB() 返回值为C++中的8位bool类型
注意【尾标】前必须是小写字母

::Kernel32.GetACP() #

返回当前ANSI代码页

::Kernel32.GetFileAttributes() #

获取参数 @1 指定路径的文件属性，文件不存在返回 -1。
参数 @1 应当使用 io.fullpath 转换为完整路径。

文件属性使用 FILE_ATTRIBUTE 前缀的常量表示。
使用 fsys.attrib 函数获取或修改文件属性更方便。

::Kernel32.GetSystemDefaultLCID() #

返回系统默认区域 ID

::Kernel32.GetThreadId(线程句柄) #

将参数 @1 指定的线程句柄转换为线程 ID 。
使用 thread.open 函数可将线程 ID 转为线程句柄。

::Kernel32.GetUserDefaultLangID() #

返回当前用户使用的默认区域语言 ID，
这与系统设置：区域语言 / 格式 一致。
可使用 sys.locale.setUserDefault 函数修改此设置

::Kernel32.LocalFree(hMem) #

一些API返回的内存句柄需要使用此函数释放，
@hMem参数指定内存句柄

::Kernel32.RtlMoveMemory(目标内存地址,源数据,源数据长度) #

复制内存
此函数支持所有API兼容指针类型参数，直接操作内存请小心使用

源数据可以是字符串、内存指针、或结构体

::Kernel32.SetDllDirectory("DLL搜索目录") #

设置加载DLL的默认目录

::Kernel32.SetDllDirectory(null) #

恢复DLL默认搜索目录

::Kernel32.SetErrorMode(0) #

显示所有系统错误对话框

::Kernel32.api("字符串参数","void()" ) #

声明Kernel32 API函数

::Kernel32.gethandle() #

返回句柄

::Shell32 成员列表 #

::Shell32.* #

可不用声明直接在此输入函数名并调用API函数

一、传入参数规则：
1、null参数不可省略
2、32位整数类型，小于32位的整数、以及枚举类型都可以直接在API参数中写数值。
3、对于任何数值类型的指针（输出参数）一律使用结构体表示，例如double * v 表示为{ double v }
4、数组使用结构体表示
5、所有结构体传给API的都是指针地址，都是输出参数并增加返回值

二、返回值规则：
1、返回值默认为int类型
2、可以使用[API尾标]改变返回值为其他类型

三、所有可用的【API尾标】:
::Shell32.ApiNameW() 切换到Unicode版本，字符串UTF8-UTF16双向转换
::Shell32.ApiNameA() 切换到ANSI版本,字符串不作任何转换
::Shell32.ApiNameL() 返回值为64位LONG类型
::Shell32.ApiNameP() 返回值为指针类型
::Shell32.ApiNameD() 返回值为double浮点数
::Shell32.ApiNameF() 返回值为float浮点数
::Shell32.ApiNameB() 返回值为C++中的8位bool类型
注意【尾标】前必须是小写字母

::Shell32.Control_RunDLL(hwnd,hinst,cmdLine,cmdShow) #

可用于启动控制面板命令,
hwnd可指定为0,hinst 可指定为 _HINSTANSE,
cmdLine 指定启动参数,cmdShow 指定为1即可,
也可以通过process.rundll 运行此函数,
或通过 process.control 直接执行控制面板命令

::Shell32.SHChangeNotify(_SHCNE,0,0,0) #

通知操作系统外壳刷新,例如刷新桌面图标等
参数依次为@eventId,@flags,@item1,@item2
参数@flags的值为5时函数名必须加上 W 尾标，即 ::Shell32.SHChangeNotifyW

::Shell32.ShellExecute(hwnd,operation,path,param,workDir,cmdShow) #

执行 path 指定的程序,
第一个参数为数值格式的句柄,
最后一个参数为数值,指定为1即可,其他参数都是字符串,
详细用法请参考该 API 文档,
注意省略的参数也要指定 null 值,
非声明式调用 API 不能减少参数个数,
raw.execute 函数提供类似功能，但所有参数都可以省略。
process.execute 函数也提供类似功能

::Shell32.api("字符串参数","void()" ) #

声明Kernel32 API函数

::User32 成员列表 #

::User32.* #

可不用声明直接在此输入函数名并调用API函数

一、传入参数规则：
1、null参数不可省略
2、32位整数类型，小于32位的整数、以及枚举类型都可以直接在API参数中写数值。
3、对于任何数值类型的指针（输出参数）一律使用结构体表示，例如double * v 表示为{ double v }
4、数组使用结构体表示
5、所有结构体传给API的都是指针地址，都是输出参数并增加返回值

二、返回值规则：
1、返回值默认为int类型,可用 >>> 0 强制转为无符号数,
2、可以使用[API尾标]改变返回值为其他类型

三、所有可用的【API尾标】:
::User32.ApiNameW() 切换到Unicode版本，字符串UTF8-UTF16双向转换
::User32.ApiNameA() 切换到ANSI版本,字符串不作任何转换
::User32.ApiNameL() 返回值为64位LONG类型
::User32.ApiNameP() 返回值为指针类型
::User32.ApiNameD() 返回值为double浮点数
::User32.ApiNameF() 返回值为float浮点数
::User32.ApiNameB() 返回值为C++中的8位bool类型
注意【尾标】前必须是小写字母

::User32.DestroyWindow() #

销毁窗口，
参数指定窗口句柄，也就是窗口对象的 hwnd 属性。
销毁窗口不会触发窗口的 onClose 事件，
但会触发 onDestroy 事件

::User32.GetAsyncKeyState() #

参数 @1 使用数值指定虚拟键码。
返回值为 16位数值，最高位表示指定物理按键是否按下。
应当将返回值与 0x8000 做按位与运算取最高位。

物理按键状态并不一定等于特定界面线程中的按键状态。
此函数忽略键盘映射，可用于非 UI 线程，
并且不能用于检测按键开关状态（nmlk,scrlk,capslk）。
key.getStateX 内部调用此函数。

::User32.GetCaretPos() #

获取输入光标的控件客户区坐标。
参数必须是接收输出值的 ::POINT 结构体。
成功返回非零值。

使用 winex.caret 可获取屏幕坐标。

::User32.GetCursorPos() #

返回鼠标当前位置,参数应当是一个::POINT结构体
成功返回非零值

::User32.GetKeyState() #

自当前线程消息队列中检测指定按键的是否按下，不一定是物理按键的真实状态。
仅可用于 U I线程，即使线徎或进程不是前台焦点，函数仍然可以工作，

参数 @1 使用数值指定虚拟键码。
返回值为 16位数值，最高位表示指定按键是否按下。
可将返回值与 0x8000 做按位与运算取最高位。
返回值的最低位表示 NumLk,CapsLk,ScrLk 的开关状态。
key.getState 内部调用此函数。

::User32.GetSystemMetrics() #

返回系统系统与数值有关的设置,宽高有关的数值以像素为单位,
参数以 SM 前缀的常量指定要获取的设置索引

::User32.GetWindowThreadProcessId(hwnd,pid) #

返回 @hwnd 参数指定窗口句柄的窗口所在线程 ID,
@pid 如果不为 null 则必须传入结构体 {addr value},
也可以改用 win.getThreadProcessId 函数

::User32.PostMessage #

通过创建目标窗口线程的消息队列发送消息给目标窗口,不等待返回，
注意消息队列等待处理的消息超过 10000 条消息时将会丢弃消息

::User32.PostMessage(hwnd,message,wParam,lParam) #

通过消息队列发送消息给目标窗口,不等待返回。
@hwnd 指定目标窗口句柄，设为 0xFFFF（65535） 则发送到所有顶层窗口。
参数@2为消息ID，一般是 WM 开头的常量。
一定要指定4个参数,省略参数输入null或0不可省略
注意不要在参数中包含在调用函数后可能释放的指针

::User32.SendMessage #

发送消息到目标窗口，并等待返回，
如果目标窗口卡住，可能导致不必要的等待过程

::User32.SendMessage(hwnd,message,wParam,lParam) #

发送消息到目标窗口，并等待返回。
@hwnd 指定目标窗口句柄，设为 0xFFFF（65535） 则发送到所有顶层窗口。
参数@2为消息ID，一般是 WM 开头的常量。
一定要指定4个参数,省略参数输入null或0不可省略

::User32.SendMessageTimeout #

发送消息到目标窗口，并可设置超时参数

::User32.SendMessageTimeout(hwnd, message, wParam,lParam,flags,timeout,pRet) #

用法请参考该 API 文档

::User32.SendNotifyMessage #

发送消息到目标窗口，
发生到调用线程创建的窗口等待窗口消息处理完消息后返回，
发生到其他线程不等待立即返回。

注意这个函数并非将消息发送到消息队列，
不会因为消息队列满被丢弃

::User32.SendNotifyMessage(hwnd,message,wParam,lParam) #

发送消息到目标窗口，
@hwnd 指定目标窗口句柄，设为 0xFFFF（65535） 则发送到所有顶层窗口。
参数@2为消息ID，一般是 WM 开头的常量。
一定要指定4个参数,省略参数输入null或0不可省略
注意不要在参数中包含在调用函数后可能释放的指针，
但对 0xFFFF 发送 _WM_SETTINGCHANGE 消息时可指定字符串参数

::User32.SetCursorPos(x,y) #

设置鼠标当前位置,参数指定x,y坐标
成功返回非零值

::User32.SystemParametersInfo(uiAction,uiParam,pvParam,fWinIni) #

设置或获取系统参数,
失败返回0,成功返回非零值,

参数@1指定 SPI 前缀常量,@pvParam 为指针或结构体指针,
其他参数都为无符号32位整数。参数 @4 设为 3 也即
_SPIF_UPDATEINIFILE | _SPIF_SENDWININICHANGE
用于刷新配置,读取值时参数 @4 设为 0 即可

这个函数的设置项非常多,细节请参考该 API 文档

::User32.api("字符串参数","void()" ) #

声明Kernel32 API函数

SubscriberObject 成员列表 #

SubscriberObject.remove() #

撤消本次订阅。

如果在需要重复创建的窗体内订阅消息，应在 winform.onDestroy 事件内取消订阅。
或改用 thread.command 可在窗体关闭后自动取消订阅。

如果只是想调用窗体的成员函数，这本来就可以直接调用，
不必使用 subscribe

_ARGV 成员列表 #

_ARGV.* #

请输入命令行参数中以斜杠或短横线开始的前导参数名。
注意参数名区分大小写

_IMPORTURL 成员列表 #

_IMPORTURL.* #

键为库名称值为远程库网址,
网址可指定 *.tar.lzma 格式安装包或 *.aardio 格式库文件,

例如:
"https://github.com/.../releases/latest/download/yourlibname.tar.lzma"
必须写在引用扩展库的语句之前

pointObject 成员列表 #

::POINT 结构体对象，包含用于表示坐标的数值字段 x,y

pointObject.x #

x坐标

pointObject.y #

y坐标

rectObject 成员列表 #

::RECT 结构体对象，包含用于表示区块位置的数值字段 left,top,right,bottom

rectObject.bottom #

下

rectObject.contains(x,y) #

检测指定的 x,y 坐标是否位于矩形区块内

rectObject.copy #

复制并返回新的矩形区块结构体

rectObject.copy() #

返回对象:rectObject

rectObject.copy(width,height) #

可选在参数中指定新的宽度、高度
所有参数都可以省略

rectObject.expand #

扩展或缩小右下角坐标

rectObject.expand() #

返回对象:rectObject

rectObject.expand(dx,dy) #

dx指定正数扩展右边,负数缩小右边,
dy指定正数扩展底边,负数缩小底边
左上角不变,
返回自身

rectObject.float() #

无参数时转换为 ::RECTF 结构体并返回该结构体
如果参数中指定::RECTF结构体,则使用参数更新位区块自身,
指定参数则此函数无返回值

返回对象:rectfObject

rectObject.height() #

高度

rectObject.inflate #

扩大区块并返回矩形区块自身

rectObject.inflate() #

返回对象:rectObject

rectObject.inflate(左右单位,上下单位) #

扩大区块并返回矩形区块自身
忽略参数请传入0,不可省略
上,下,左,右分别扩大指定的单位
负数为缩小

rectObject.intersect #

检测与参数指定的矩形区块相交

rectObject.intersect(rc) #

检测与参数指定的矩形区块相交
成功修改当前区块并返回自身,失败返回空

rectObject.intersectsWith #

检测两个矩形区块是否碰撞相交

rectObject.intersectsWith(rc) #

检测两个矩形区块是否碰撞相交

rectObject.left #

左

rectObject.ltrb #

用于将 x,y,width,height 转换为 left,top,right.bottom 并返回

rectObject.ltrb() #

返回结构体的 left,top,right,bottom 等4个值

rectObject.ltrb(x,y,width,height) #

使用传入参数修改左、上坐标,以及宽度、高度,
返回结构体的left,top,right,bottom等4个值

rectObject.move #

移动左上角坐标

rectObject.move() #

返回对象:rectObject

rectObject.move(dx,dy) #

使用参数指定的x,y坐标偏移量移动左上角坐标,
正数向右下移动,负数向左上移动,
右下角位置不变
返回自身
如果需要移动坐标且大小不变请改用offset函数
移动到指定坐标而不是偏移量请改用setPos函数

rectObject.offset #

移动矩形框并返回自身

rectObject.offset() #

返回对象:rectObject

rectObject.offset(横偏移,纵偏移) #

移动矩形框并返回自身,矩形大小不变,
左上移使用负坐标,右下移使用正坐标
忽略参数请传入0,不可省略

rectObject.right #

右

rectObject.setPos #

重新调整坐标与大小,
返回结构体自身

rectObject.setPos() #

返回对象:rectObject

rectObject.setPos(x,y,cx,cy) #

移动到x,y指定的坐标,
可选用cx,cy重新指定宽度和高度,
所有参数可选,不指定则保持旧值

rectObject.top #

上

rectObject.width() #

宽度

rectObject.xywh #

用于将left,top,right.bottom转换为 x,y,width,height 并返回

rectObject.xywh() #

返回结构体的左上角坐标x,y 以及宽度width,高度height等4个值

rectObject.xywh(left,top,right,bottom) #

修改左、上、右、下的值,
返回结构体的左上角坐标x,y 以及宽度width,高度height等4个值

sizeObject 成员列表 #

::SIZE 结构体对象，包含用于表示大小的数值字段 cx,cy

sizeObject.cx #

宽

sizeObject.cy #

高

type 成员列表 #

对象类型检测

类型检测函数

type(需要返回数据类型的变量) #

检测数据类型,返回值1为基本数据类型
如果返回两个或三个值，最后的返回值为元表中_type的值,
结构体返回三个值，第二个返回值为结构体声明

type.boolean #

布尔值：基本数据类型

type.buffer #

原生字节数组：基本数据类型
由 raw.buffer 函数分配的可读写、固定长度的内存，
可用于存取各种二进制数据，几乎所有字符串函数中都可以作为字符串使用。

type.callable() #

判断参数是否函数、类、或其他可调用对象

type.cdata #

内核对象：基本数据类型

type.class #

类：基本数据类型

type.eq(, ) #

比较两个对象的数据类型、元类型、结构体类型是否完全相同,
如果一个函数的返回值用于逻辑判断，此类函数返回布尔值（true,false），
在aardio 一个说明返回布尔值的函数，实际允许返回任意类型的值，
如果此类函数无返回值，应视为返回 null值，
如果此类函数返回 null 值，应视为 false 值，
具体请参考 aardio 基础语法文档中的说明，
aardio支持宽松的类型转换，在其他类似函数中不再做额外说明

type.fiber #

纤程：基本数据类型

type.file #

元类型名"io.file"。
使用 io.file 打开的文件以及标准输入输出对象的元类型。

type.function #

函数：基本数据类型

type.isFile() #

参数 @1 如果是 io.file,fsys.file,fsys.stream 对象则返回 true。

type.isString() #

参数 @1 如果是 string 或 buffer 类型返回 true

type.null #

空值：基本数据类型

type.number #

数值：基本数据类型

type.pointer #

指针值：基本数据类型

type.rget() #

调用type函数检测对象类型
并返回最后一个类型描述
type 函数检测一个对象时，可能返回一个或多个类型描述，
分别为数据类型、元类型、结构体类型

type.string #

字符串：基本数据类型

type.table #

表：基本数据类型

全局常量

::CopyMemory(目标内存地址,源地址,源数据长度) #

复制内存
此函数调用::Kernel32.RtlMoveMemory

::CopyMemoryByStruct(目标内存地址,源结构体,源结构体长度) #

复制结构体到目标内存
此函数调用::Kernel32.RtlMoveMemory

::FILETIME() #

FILETIME 结构体,
用于表示自 1601年1月1日 开始以 100纳秒 为间隔的数值。
100纳秒 也就是 0.0001毫秒。

此结构体包含 2 个 32 无符号位整数字段：dwLowDateTime,dwHighDateTime。

标准库 fsys.time 可创建 ::FILETIME 兼容结构体，
并且提供了更多功能

::GetLastError() #

返回系统错误代码

::GetModuleHandle(模块名) #

返回动态链接库的模块句柄

::GlobalAlloc(分配选项,内存长度) #

在进程堆上分配内存,
分配选项可选参数如下:

0x40/*_GPTR*/ 返回指针,内存数据初始化为零
0x42/*_GHND*/ 返回句柄,内存数据初始化为零,
0x0/*_GMEM_FIXED*/ 返回指针
0x2/*_GMEM_MOVEABLE*/ 返回句柄
内存句柄需要调用 ::GlobalLock 函数转换为内存指针

::GlobalFree(内存句柄) #

释放::GlobalAlloc()分配的内存
如果成功返回null,否则返回传入句柄

::GlobalLock(内存句柄) #

锁定::GlobalAlloc(0x2/*_GMEM_MOVEABLE*/)创建的内存句柄,
并返回内存指针指针

::GlobalReAlloc(内存句柄,新的长度,分配选项) #

改变GlobalAlloc函数申请的内存大小
分配选项参考 GlobalAlloc() 说明

::GlobalSize(内存句柄) #

获取内存长度

::GlobalUnlock(内存句柄) #

解锁::GlobalAlloc(0x2/*_GMEM_MOVEABLE*/)创建的内存句柄,
成功返回true

::HIBYTE #

function(l) {return   (l   >> 8) & 0xff  }

::HIWORD #

function(l) {return  (l >> 16) & 0xffff }

::Kernel32 #

默认已加载的Kernel32.dll模块对象
Kernel32.dll是Windows内置库,提供很多常用API

::LOBYTE #

function(l) {return l  & 0xff }

::LOWORD #

function(l) {return l & 0xffff }

::MAKELONG #

function(a,b){ return ( ( (b & 0xFFFF) << 16) | (a & 0xFFFF) ) & 0xFFFFFFFF }

::MAKEWORD #

function (a,b){ return ( ( ( b & 0xFF) << 8) | ( a & 0xFF) ) & 0xFFFF  }

::Ntdll #

默认已加载的系统DLL组件ntdll.dll

返回对象:dllModuleObject

::OffsetRect(rc,dx,dy) #

移动矩形框，
此函数已废弃，请直接调用 rc.offset 函数

::POINT #

整型坐标结构体
此结构体通过标准库 builtin.struct 默认加载

::POINT() #

返回对象:pointObject

::POINT(x,y) #

创建整型坐标结构体
可选在参数中指定 x,y 坐标初始值

::RECT #

表示矩形区块的结构体
此结构体通过标准库 builtin.struct 默认加载

::RECT() #

返回对象:rectObject

::RECT(left,top,right,bottom) #

创建矩形区块结构体
可选在参数中指定左,上,右,下初始值

::SIZE #

整型尺寸结构体
此结构体通过标准库 builtin.struct 默认加载

::SIZE() #

返回对象:sizeObject

::SIZE(cx,cy) #

创建整型尺寸结构体
可选在参数中指定宽高 cx,cy 初始值

::Shell32 #

默认已加载的Shell32.dll模块对象（参考标准库：peload.io），
提供Windows系统外壳 API

::Ucrtbase #

UCRT 运行时，
Windows 10 以及之后的系统已经自带了 UCRT。

加载此 DLL 的代码如下：
::Ucrtbase := ..raw.loadDll("ucrtbase.dll",,"cdecl");
注意等号前必须加冒号。

返回对象:dllModuleObject

::User32 #

默认已加载的User32.dll模块对象
User32.dll提供Windows用户界面相关API

_AARDIO_VERSION #

aardio 内核版本号

_ARGV #

解析后的进程启动参数表，已解析双引号、命令行参数转义符等并转换为数组,
命令行解析规则请参考标准库中 string.cmdline 的源码,

ARGV 既包含命令行参数数组,也包含按下列规则解析的键值对:
以斜杠或短横线开始的前导参数作为键(键名移除一个或多个相同的前导字符,区分大小写)，
如果前导参数包含等号,则以等号拆分为键值对,等号前后不应有空格,
否则检查下一参数如果没有相同的首字符则设为此键对应的值，
如果一个前导参数没有指定值,则默认值为空字符串（逻辑值为true）

_ARGV仅在发布后的进程启动线程中存在,开发环境中 _ARGV 为空表。
非主线程请改用 thread.cmdline

_CMDLINE #

命令行参数的原始文本
也可以使用 _ARGV 获取解析后的命令行参数
_CMDLINE 仅在启动线程中存在,一般用于main.aardio,开发环境中为null
可使用#操作符检测参数是否为空

_HAPPICON #

应用程序图标句柄，可在工程属性中自定义该图标，
图标在不再使用时会自动释放,不要手动释放该图标
_HAPPICON仅在启动线程中存在

_HINSTANSE #

当前应用程序的实例句柄

_IMPORTURL #

用于注册远程扩展库安装网址的表,
可添加新的键值，键为库名称，值为库安装文件网址,
网址可指定 *.tar.lzma 格式安装包或 *.aardio 格式库文件"
必须写在引用扩展库的语句之前

_INVALID_HANDLE_VALUE #

topointer(-1)
表示无效句柄

_STUDIO_INVOKED #

检测程序是否在 aardio 开发环境内运行。

可能的值如下：

• 值为 "process": aardio 程序是在开发环境内以独立的进程模式运行。

• 值为 "thread": aardio 程序是在开发环境主进程内以线程模式运行。

└── 在开发环境内启动并且首个 import 语句导入的是 ide 库即以线程模式运行。

└── 为保持开发环境的稳定与独立性，任何时候都不建议使用线程模式。

• 值为 "external": 外部程序在非主线程内将开发环境设为应用根目录，并且导入了 ide 库。
  

└── 此模式可启用自动安装扩展库等功能。

• 值为 null : 表明 aardio 程序不是由开发环境启动，并且未在非主线程导入 ide 库。

_WIN10_LATER #

当前系统是否为WIN10/Win2016或之后的版本

_WIN7_LATER #

当前系统是否为WIN7/Win2008 R2或之后的版本

_WINE #

如果程序在 Linux(Wine、CrossOver) 环境下运行此常量包含wine版本号
否则为 null

_WINXP #

当前系统是否为WINXP或Win2003
否则为Vista/WIN2008或以后的版本

_WIN_64 #

_WIN_64 = 当前系统是否为64位

_WIN_VER_BUILD #

Windows 构建版本号
Windows10 构建版本号与发行版本号的对应关系请参考 win.versionEx

_WIN_VER_MAJOR #

Windows 主版本号

_WIN_VER_MINOR #

Windows 副版本号

自动完成常量

_CP_ACP=0
_CP_UTF16_BE=1201
_CP_UTF16_LE=1200
_CP_UTF8=65001
_MAX_PATH_U16=0x208
_MAX_PATH_U8=0x410
_O_BINARY=0x8000
_O_TEXT=0x4000
_SH_DENYNO=0x40
_SH_DENYRD=0x30
_SH_DENYRW=0x10
_SH_DENYWR=0x20
_SH_SECURE=0x80

Markdown 格式