# win.ui.tabs 库模块帮助文档 [高级选项卡使用指南](https://www.aardio.com/zh-cn/doc/library-guide/std/win/ui/tabs/_.html) ## win.ui.tabs 成员列表 # 高级选项卡（ win.ui.tabs ）。高级选项卡并不是一个控件，而是用于管理一组 plus 控件（ win.ui.ctrl.plus ）以实现选项卡效果的管理组件。创建高级选项卡（ win.ui.tabs ）。自动查找附近合适的 custom 控件作为页面容器。优先选择未禁用、未隐藏、未设置透明的 custom 控件。如果是水平选项卡，应在下侧放置 custom 控件作为页面容器, 如果是垂直选项卡,应在右侧放置 custom 控件作为页面容器。为了避免在启动软件时一次性加载大量子窗口导致启动速度慢, 为每一个选项卡添加子窗口时，win.ui.tabs 默认会创建并返回伪窗口。直到点击该选项卡或访问伪窗口的属性与方法（fake 属性除外）时才会真正初始化相应的子窗口 ### win.ui.tabs.defaultStyle # ```aardio win.ui.tabs.defaultStyle = { foreground={ active=0xFFFFFFFF; default=0x00FFFFFF; hover=0x38FFFFFF }; color = { default=0xFFFFFFFF; }; checked={ foreground={default=0xFFFFFFFF;}; color={default=0xFF42A875;};/*默认选项卡样式*/ } } ``` ### win.ui.tabs.dropButtonStyle # ```aardio win.ui.tabs.dropButtonStyle = { color = { hover = 0xff99ffcc; active = 0xffff6666; default = 0xffffffff; }/*选项卡下拉按钮默认样式*/ } ``` ## win.ui 成员列表 # ### win.ui.tabs() # [返回对象:winUiTabsObject](#winUiTabsObject) ### win.ui.tabs(headerTab1,headerTab2) # 创建高级选项卡。参数必须指定至少2个已创建的 plus 控件模板,对象创建成功可选清除模板如果不需要动态增删选项卡,参数中的 plus 控件无需保持均匀间隔, 动态增加选项卡时会根据模板控件的样式与位置, 自动分析是水平排列还是垂直排列,自动分析排列间距，并动态添加选项卡,可选显示删除选项卡的按钮添加的选项卡数目超出显示范围时可自动折叠到下拉菜单，自动折叠功能会保证新增选项卡、当前选项卡位于可见位置, 这会导致选项卡在必要时自动调整位置, 所以同一索引并不一定指向同一选项卡 ## winUiTabsObject 成员列表 # ### winUiTabsObject.add(tabButtonPropertiesTable) # ```aardio winUiTabsObject.add({ text="选项卡按钮标题"; iconText='\uF0AD'; foreground="\res\images\icon.png"; hasCloseButton=true;/*添加选项卡按钮（plus 控件）。参数 @1 可以用一个表（table）指定部分创建 plus 控件的属性，未指定的属性自动补全, text 属性可用于指定显示文本,foreground 属性可用于指定前景图标。如果指定 hasCloseButton 属性为 true，鼠标悬停在选项卡按钮上会显示关闭按钮, 参数 @1 也可以传入一个 plus 按件初始化属性表数组，用于同时创建多个选项卡按钮。如果存在多个调用参数，自参数 @2 开始作为 loadForm 的调用参数以执行高级选项卡的 loadForm 方法加载子窗体，并绑定当前选项卡按钮。此函数成功返回新增的选项卡按钮索引。如果超出显示范围，新增选项卡按钮会自动替换到最后一个显示位置，并将被替换的选项卡按钮移入到下拉菜单内。*/ }) ``` ### winUiTabsObject.addItems(arrayTabPropertiesTable) # 参数 @arrayTabPropertiesTable 指定一个属性表数组，遍历数组中的控件属性表并作为参数调用高级选项卡的 add 方法创建多个选项卡。调用参数 @arrayTabPropertiesTable 为 null 或空数组时忽略不执行任何操作 ### winUiTabsObject.adjust() # ```aardio winUiTabsObject.adjust = function(){ var x,y,cx,cy = owner.getPos(); /*选项卡已重新调整布局*/ } ``` ### winUiTabsObject.adjustLayout() # 调整布局高级选项卡会在需要的时候自动调用此函数 ### winUiTabsObject.beforeShowCloseButton(tabButton,rcTabItem,rcCloseButton,dpiScaleX,dpiScaleY) # ```aardio winUiTabsObject.beforeShowCloseButton = function(tabButton,rcTab,rcCloseButton){ /*返回关闭按钮显示的x,y坐标,需要返回2个值不返回值取消显示参数 tabButton 为请求显示关闭按钮的选项卡按钮。 rcTab 为选项卡按钮所在的位置区块,::RECT对象, rcCloseButton为关闭按钮所在的的区块,::RECT对象 dpiScaleX,dpiScaleY为X,Y轴上的DPI缩放比例,1表示100%*/ } ``` ### winUiTabsObject.clear() # 清空所有选项卡按钮、清空所有加载的子窗口 ### winUiTabsObject.closeButton # 选项卡按钮上动态显示的关闭按钮，这是一个 plus 控件。可调用 skin 函数自定义外观样式。可通过 beforeShowCloseButton 事件自定义显示坐标。注意这是一个 orphanWindow 浮动窗口。 [返回对象:uiCtrlPlusObject](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/ctrl/plus.html#uiCtrlPlusObject) ### winUiTabsObject.count # 返回高级选项卡包含的选项总数 ### winUiTabsObject.create() # [返回对象:uiCtrlPlusObject](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/ctrl/plus.html#uiCtrlPlusObject) ### winUiTabsObject.create(参数表) # 此函数与 add 函数用法相同但创建选项卡以后会同时创建对应的子窗口, 返回 2 个值,分别为创建的选项卡按钮对象、子窗体对象。注意,调用 add,create 函数添加选项卡按钮, 如果超出可见范围,会自动折叠其他选项卡按钮,并将新增的选项卡按钮移动到可见位置。所以增加选项卡按钮可能导致选项卡按钮调整位置,选项卡按钮的原索引发生变化 ### winUiTabsObject.delete(tabIndex)) # 删除指定索引的选项卡按钮。参数用数值指定选项所在位置索引 ### winUiTabsObject.deleteByForm(formPage) # 删除指定的选项卡按钮。参数指定相同索引位置的子窗体对象 ### winUiTabsObject.deleteByTab(tabButton)) # 删除指定的选项卡按钮。参数指定选项卡按钮对象 ### winUiTabsObject.disabled # 是否禁用选项卡。仅当前选项卡按钮会切换禁用样式，其他选项按钮仅切换是否允许响应事件属性（notify）。如果尚未指定当前选项，则获取此属性时总是为 false 。 ### winUiTabsObject.disabledText # ```aardio winUiTabsObject.disabledText = {'\uF254';'\uF251';'\uF252';'\uF253';'\uF250'}/*指定文本时,指定为文本或文本数组则禁用当前选项按钮并显示指定文本，同时也会禁止所有选项卡按钮响应事件（但其他选项卡按钮不显示禁用样式），禁止切换选项。此属性指定为一个文本数组时,当前选项卡按钮将创建动画逐帧显示数组里的文字图标。如果当前选项卡按钮配置了图标文本则使用图标文本（ iconText ）显示数组内的文字图标, 此属性指定为 null 时，启用当前选项，并恢复控禁用之前的 text、iconText 属性。同时其他所有选项卡按钮也会切换到允许响应事件（notify 属性恢复为 true ）。如果尚未指定当前选项，则获取此属性时总是为 null。*/ ``` ### winUiTabsObject.dropButton # 下拉菜单按钮。如果存在超出显示范围的选项卡按钮，这个 dropButton 控件会自动显示。 dropButton 是一个 plus 控件对象。 [返回对象:uiCtrlPlusObject](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/ctrl/plus.html#uiCtrlPlusObject) ### winUiTabsObject.dropButtonMargin # 下拉菜单按钮边距 ### winUiTabsObject.each() # ```aardio for(tabButton,formPage,tabIndex in winUiTabsObject.each() ){ /*遍历高级选项卡的所有选项。 tabButton 为当前选项卡按钮,formPage 为对应的子窗口,tabIndex 为索引位置遍历时不应当执行删除、新增选项，更改当前选项等所有可能改变高级选项卡索引的操作。*/ } ``` ### winUiTabsObject.getPos() # 返回x,y,cx,cy等4个值, 分别表示高级选项卡当前左,上坐标,宽度,高度 ### winUiTabsObject.getText(tabIndex) # 返回指定索引选项卡按钮的显示文本。 ### winUiTabsObject.hitTest(x,y) # 参数指定屏幕坐标，返回该坐标所在的选项卡，以及选项索引 ### winUiTabsObject.indexOfForm() # 获取子窗口所在的选项索引位置参数指定相同索引位置的子窗体对象 ### winUiTabsObject.indexOfTab() # 获取选项卡按钮所在的索引位置参数指定选项卡按钮对象 ### winUiTabsObject.initPopup(handleCtrl,transparent) # 初始化为弹出菜单样式 @handleCtrl指定接收输入事件的控件, 自动修改该控件的checked属性为是否弹出状态, transparent指定菜单是否透明, 所有参数可选 ### winUiTabsObject.isVisible() # 选项卡是否可见 ### winUiTabsObject.itemMargin # 选项卡间隔距离,可以为负数 ### winUiTabsObject.keepSpace # 是否保持选项之间的间距不变, 该属性建议由aardio自动设置 ### winUiTabsObject.lastVisibleIndex # 最后一个显示状态的选项卡索引在这后面是因为超出显示范围被自动隐藏的选项卡 ### winUiTabsObject.lastVisibleItem # 最后一个显示状态的选项卡在这后面是因为超出显示范围被自动隐藏的选项卡这是一个plus控件对象 [返回对象:uiCtrlPlusObject](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/ctrl/plus.html#uiCtrlPlusObject) ### winUiTabsObject.loadForm # 加载窗体到高级选项卡的页面容器控件，并绑定选项卡。选项卡必须已经匹配到可用的页面容器，也就是说 panel 属性不为空值。高级选项卡默认会自动查找附近合适的 custom 控件作为页面容器也可以手动指定 panel 指向的窗口 loadForm 函数默认会加载延迟创建实际窗口的伪窗口。访问伪窗口的任何属性或方法都会自动创建真实窗口。 ### winUiTabsObject.loadForm() # 在页面容器控件创建默认子窗体并绑定到最后一个选项卡。返回创建的子窗口对象。 ### winUiTabsObject.loadForm(tabIndex) # 在页面容器控件创建默认子窗体并绑定到指定的选项卡。数 @tabIndex 指定索引，可用负索引表示倒计数，-1 表示最后一个选项卡。如果不指定索引则默认取 forms 属性的数组长度并加 1 作为索引。与其他函数同的是：此函数省略参数 @1 可不用占位，允许参数 @2 写为参数 @1。省略参数 @2 则立即创建默认子窗体并加载到页面，然后返回该窗体。 ### winUiTabsObject.loadForm(tabIndex,"请输入窗体代码文件路径") # 在页面容器控件内预加载创建子窗体的代码文件，并绑定到参数 @tabIndex 指定索引的选项卡。参数 @tabIndex 可用负索引表示倒计数，-1 表示最后一个选项卡。在开发环境中,请注意保存外部窗体文件以后测试运行。默认会创建并返回一个伪窗口对象，并延迟到用户切换到所属选项卡时才会真正创建窗口。访问伪窗口除 fake 以外的任何属性方法也会立即创建窗口。 ### winUiTabsObject.loadForm(tabIndex,@tParam) # 在页面容器控件内创建子窗体并绑定到参数@1指定索引的选项卡。参数 @tabIndex 可用负索引表示倒计数，-1 表示最后一个选项卡。默认会创建并返回一个伪窗口对象，并延迟到用户切换到所属选项卡时才会真正创建窗口。访问伪窗口除 fake 以外的任何属性方法也会立即创建窗口。 ### winUiTabsObject.loadForm(tabIndex,winform) # 将 @winform 指定的子窗体添加到页面容器，并绑定到参数 @tabIndex 指定索引的选项卡。参数 @tabIndex 可用负索引表示倒计数，-1 表示最后一个选项卡。如果不指定索引（可省略参数占位）则默认取 forms 属性的数组长度并加 1 作为索引。返回参数 @2 指定的窗体对象。 ### winUiTabsObject.margin # 可设置选项卡按钮尾部最少预留的边距, 超出显示范围时自动折叠选项卡并在此显示下拉菜单，默认会根据下拉按钮的大小自动设置此值, 如果设置为0则禁用自动折叠功能。此属性应设置为系统 DPI 缩放前的原始值 ### winUiTabsObject.next() # 切换到下一个选项 ### winUiTabsObject.oncommand(tabButton,id,event) # ```aardio winUiTabsObject.oncommand = function(tabButton,id,event){ /*点击选项卡按钮触发此函数 tabButton 为触发事件的选项卡按钮对象（plus 控件）。 id 为按钮的控件 id,event目前值总是 0*/ } ``` ### winUiTabsObject.panel # 用于构成选项卡内容区域（ tab body area ）的容器控件。必须是一个 custom 控件（win.ui.ctrl.custom 控件）。创建高级选项卡时，panel 属性会自动指定为附近可用的 custom 控件。也可以在加载子窗口以前手工指定此对象 [返回对象:winform](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/_.html#winform) ### winUiTabsObject.popup 切换到弹出列表模式，用于显示简单的弹出列表或菜单，如果当前项目列表数组为空,则无论传入什么参数都会切换到隐藏状态 ### winUiTabsObject.popup(false) 隐藏列表，并将selIndex置为null 如果当前项目列表数组为空,则无论传入什么参数都会切换到隐藏状态 ### winUiTabsObject.popup(true,ctrl,mode) 弹出列表 ctrl指定控件，弹出列表显示在该控件边上, 自动修改该控件的checked属性为是否弹出状态, 可选使用mode参数指定"up","down","left","right"等显示位置 ### winUiTabsObject.popup(true,x,y) 弹出列表可选使用x,y指定列表左上角在屏幕上的坐标 ### winUiTabsObject.prev() # 切换到上一个选项 ### winUiTabsObject.query() # [返回对象:winform](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/_.html#winform) ### winUiTabsObject.query(查询属性表) # ```aardio winUiTabsObject.query( text = "标题"; tabsName = "名字";/*使用选项卡按钮的指定属性查询对应的子窗口（formPage）。如果子窗口是延迟加载状态则会立即加载。选项卡的任一属性值与查询条件相同即可，不需要匹配所有查询属性。自定义属性建议加上 data 前缀以避免与控件属性混淆。也可以用一个字符串参数直接查询选项卡按钮的标题。返回选项卡按钮对应的子窗口对象,以及所在选项索引（数值）.*/ ) ``` ### winUiTabsObject.queryTab() # [返回对象:uiCtrlPlusObject](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/ctrl/plus.html#uiCtrlPlusObject) ### winUiTabsObject.queryTab(查询属性表) # ```aardio winUiTabsObject.queryTab(text = "标题"/*使用控件的指定属性查询对应的选项卡按钮，选项卡按钮的任一属性值与查询条件匹配即可，不需要满足所有查询条件。用户自定义属性建议加上 data 前缀以避免以控件已有属性名称冲突。也可以用一个字符串参数直接查询选项卡按钮的标题, 返回选项卡按钮对象,以及所在索引数值*/) ``` ### winUiTabsObject.selForm # 当前选中的子窗口 [返回对象:winform](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/_.html#winform) ### winUiTabsObject.selIndex # 获取或指定当前选中项索引,设为 null 清除当前选项, 如果新的选中项已被自动折叠,则会自动移动到可见位置所以设置selIndex时可能导致selIndex移动位置 ### winUiTabsObject.selTab # 获取或指定当前选中的选项卡按钮指定 null 或不存在于 tabs 中的控件时清除选中项, [返回对象:uiCtrlPlusObject](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/ctrl/plus.html#uiCtrlPlusObject) ### winUiTabsObject.selText # 获取当前选中项文本, 也可以指定一个文本用于切换到显示该文本的选项卡 ### winUiTabsObject.set(tabIndex,tabProperties) # 设置 @tabIndex 参数指定索引的选项卡按钮属性。 @tabProperties 参数指定控件属性表。 ### winUiTabsObject.setItemTexts # 使用文本数组更新选项卡数组, 此函数可重用已创建的选项卡，所以有更好的性能 ### winUiTabsObject.setItemTexts(texts,limit,selIndex) # 使用参数@texts指定的字符串数组创建选项卡数组, 其中的每个字符串用于指定选项卡上的显示文本。可选用@limit参数指定最大显示条数, 可选用@selIndex参数指定默认选中索引, 此函数返回实际显示条数 ### winUiTabsObject.setItems # 使用控件初始化选项数组更新选项卡数组, 此函数可重用已创建的选项卡，所以有更好的性能 ### winUiTabsObject.setItems(items,limit,selIndex) # 使用参数@items指定的选项数组更新选项卡数组, 每个选项提供控件的初始化属性并将被传入add函数。可选用@limit参数指定最大显示条数, 可选用@selIndex参数指定默认选中索引, 此函数返回实际显示条数 ### winUiTabsObject.setTabs(属性名,属性值数组) # 批量设置所有选项卡按钮（plus 控件）的指定属性值。参数 @2 应传入一个属性值数组，函数会遍历属性值数组，并设置相同索引的选项卡按钮。第 1 个选项卡按钮设置第 1 个属性值，第 2 个选项卡按钮设置第 2 个属性值，依此类推。 ### winUiTabsObject.show(可选输入显示参数) # 显示或隐藏所有选项卡按钮,可选输入以 _SW_ 为前缀的显示参数（数值）。参数@1也可以传入 true,false 控制是否显示选项卡 ### winUiTabsObject.showDropButton(true) # 参数为true显示下拉菜单按钮参数为 false 隐式该按钮高级选项卡会在需要的时候自动调用此函数 ### winUiTabsObject.skin # ```aardio winUiTabsObject.skin({ background = { hover = "/res/images/button-hover.png"; focus = "/res/images/button-focus.png"; active = "/res/images/button-active.png"; disabled = 0xFFCCCCCC; }; color = { hover = 0xF00000FF;/*用格式为0xAARRGGBB的16进制数值,指定鼠标放到控件上的字体颜色, AA为透明度,RR为红色分量,GG为绿色分量,BB为蓝色分量*/ }; border = { hover = {left=5;color=0xFFFF0000;padding=15;} }; }) ``` ### winUiTabsObject.swap(tabIndex,tabIndex2) # 交换两个索引的选项卡位置参数 tabIndex,tabIndex2 应当是有效的选项卡索引这个函数如果没有弄清楚原理最好不要使用, 高级选项卡会在需要的时候自动调用此函数, 成功返回true,失败返回null ### winUiTabsObject.updateItemRegion() # 更新选项卡绘图区域, 参数必须是兼容 win.region.png 接口的对象 ## winUiTabsObject 事件列表 # ### winUiTabsObject.onCancel() # ```aardio winUiTabsObject.onCancel = function(){ /*用户关闭弹出列表并且未确认选项*/ } ``` ### winUiTabsObject.onDrawEnd # ```aardio winUiTabsObject.onDrawEnd = function(graphics,rc){ /*所有绘制操作结束触发此事件, graphics 为gdip.graphics对象(GDI+画板), rc为客户区RECT结构体*/ } ``` ### winUiTabsObject.onDrawForegroundEnd # ```aardio winUiTabsObject.onDrawForegroundEnd = function(graphics,rc,rcContent){ /*背景前景绘制后,绘制文本前触发此事件, graphics 为 gdip.graphics 对象（GDI+ 画板）, rc为客户区 RECT 结构体,rcContent 为去掉内边距后的RECT结构体*/ } ``` ### winUiTabsObject.onDrawString(...) # ```aardio winUiTabsObject.onDrawString(...onDrawString = function(graphics,text,font,rectf,strformat,brush){ graphics.drawString(text,font,rectf,strformat,brush); /*自绘所有选项卡控钮上的文本。注意 owner 参数指向当前选项卡按钮*/ } ``` ### winUiTabsObject.onFocusGot(hLostFocus) # ```aardio winUiTabsObject.onFocusGot = function(hLostFocus){ ..win.setFocus(hLostFocus);/*得到焦点触发此事件,hLostFocus为失去焦点的窗口句柄*/ } ``` ### winUiTabsObject.onFocusLost(hFocus) # ```aardio winUiTabsObject.onFocusLost = function(hFocus){ /*失去焦点触发此事件,hFocus 为得到焦点的窗口句柄*/ } ``` ### winUiTabsObject.onMouseDown(tabButton,wParam,lParam) # ```aardio winUiTabsObject.onMouseDown = function(tabButton,wParam,lParam){ /*在选项卡按钮 tabButton（plus 控件）上按下鼠标，即将切换当前选项卡。 wParam,lParam为窗口消息参数*/ } ``` ### winUiTabsObject.onMouseHover(tabButton,wParam,lParam) # ```aardio winUiTabsObject.onMouseHover = function(tabButton,wParam,lParam){ /*鼠标正悬浮于选项卡按钮 tabButton 之上, wParam,lParam为窗口消息参数*/ } ``` ### winUiTabsObject.onMouseLeave(tabButton,wParam,lParam) # ```aardio winUiTabsObject.onMouseLeave = function(tabButton,wParam,lParam){ /*鼠标离开选项卡按钮 tabButton, wParam,lParam为窗口消息参数*/ } ``` ```aardio winUiTabsObject.onMouseLeave = function(tabButton,wParam,lParam){ /*鼠标离开选项卡按钮 tabButton, wParam,lParam为窗口消息参数*/ } ``` ### winUiTabsObject.onMouseUp(tabButton,wParam,lParam) # ```aardio winUiTabsObject.onMouseUp = function(tabButton,wParam,lParam){ /*在选项卡按钮 tabButton（plus 控件）上放开鼠标，选项卡切换操作已完成, wParam,lParam为窗口消息参数*/ } ``` ### winUiTabsObject.onOk(tabButton) # ```aardio winUiTabsObject.onOk = function(tabButton){ /*用户在弹出列表中选择并确认选项,且即将关闭弹出列表*/ } ``` ### winUiTabsObject.onPopup(showing) # ```aardio winUiTabsObject.onPopup = function(showing){ /*弹出状态变更时触发此事件弹出状态@showing参数为true，显示为弹出状态@showing参数为false*/ } ``` ### winUiTabsObject.onSelChange(tabIndex,tabButton,formPage) # ```aardio winUiTabsObject.onSelChange = function(tabIndex,tabButton,formPage){ /*切换选项会触发此事件,tabIndex 为当前选中索引 tabButton 为当前选项卡按钮对象，formPage 为当前子窗口。如果在这里禁用选项卡或 tabButton，则不会自动触发 tabButton 的其他事件。*/ } ``` ### winUiTabsObject.onVisualStateChanged(showing) # ```aardio winUiTabsObject.onVisualStateChanged = function(showing){ /*显示或隐藏时触发此事件显示 @showing 参数为 true，隐藏 @showing 参数为false*/ } ``` ## winUiTabsObject.forms 成员列表 # 用于显示页面内容的子窗口数组，选中的子窗口将在 panel 属性指定的容器控件中显示。 ### winUiTabsObject.forms.* # 子窗口是 win.form 对象 [返回对象:winform](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/_.html#winform) ## winUiTabsObject.tabList 成员列表 # 用于构成选项卡头部区域（ tab header area ）的选项卡按钮数组。所有选项卡按钮都是 plus 控件（win.ui.ctrl.plus 控件）。 ### winUiTabsObject.tabList.* # 选项卡按钮数组包含的按钮对象。所有选项卡按钮都是 plus 控件（win.ui.ctrl.plus 控件）。 [返回对象:uiCtrlPlusObject](https://www.aardio.com/zh-cn/doc/library-reference/win/ui/ctrl/plus.html#uiCtrlPlusObject)