### Supcan Tree组件

Supcan Tree组件是一个简单的树控件组件，从MFC的CTreeCtrl类继承，插件/加载项能将其展示到页面。
树是根据一个XML(或JSON)创建的，该XML可以是一个URL，也可以是一个XML串。
1.创建实例

Supcan Tree组件是通过插件/加载项创建的，所以应该用使用指南 \ 页面语法中叙述的插件/加载项的页面创建语法创建， <Object>中的某几个Param参数规则如下:

    <Object ...(略)>
    <Param name="CtlName" value="BCV1.Tree">　　//固定
    <Param name="ZipUrl" value="BCV1.bin">	　　//也可以是绝对URL
    <Param name="CtlPara" value="Border=single,3D;  NodeImage=2;  BackPicture=../res/trade.gif">	//例子
    ...

如果页面是直接调用dynaload.js，那么可能就是这样:

    insertTree('AF', 'Border=single,3D;  NodeImage=2;  BackPicture=../res/trade.gif')

CtlPara参数决定了如何在页面上展现Supcan Tree实例，在上面的例子中，参数串中可包含多个子串，子串间以 "；" 分隔。子串的名值对的规范如下： |

子串名 | 含义 | 可用值 | 默认值
Border | 边界 | 1.none - 无边界 2.single - 单线条边界 3.3dLower(或3d) - 3D凹进边界 4.3dRaise - 3D凸起边界 | single
BorderColor | 边界色 | 颜色，仅用于Border=single | #7f9db9
Style | 显示风格 | 可以包含如下串，同时选用则以逗号分隔: 1.hasButton - 含有展开/收拢的+/-小按钮 2.hasLine - 含有树的连接线 3.hasCheckBox - 左侧含有CheckBox 4.singleExpand - 不能同时展开多个节点 5.showSelAlways - 始终显示当前选择项焦点 6.editLabel - 允许编辑文字 | (无)
lineHeight | 行高 | 像素数 | 19
NodeImage | 树杈的默认图标 | -1表示不显示图标，0至3表示采用如下图标中的一个： 也可以是外部自定义的图片文件的URL(支持图片扩展URL) | 0
LeafImage | 树叶的默认图标 | -1表示不显示图标，0至12表示采用如下图标中的一个： 也可以是外部自定义的图片文件的URL(支持图片扩展URL) | 0
bgColor 或BackColor | 背景色 | 颜色，如果是以逗号分隔的2个颜色值，则表示在垂直方向的渐变 | (无)
Picture 或 BackPicture | 背景图 | 图片的URL，支持图片扩展URL | (无)
arrange | 背景图片显示方式 | 1.tile - 平铺 2.stretch - 伸展 3.单幅原样显示，须是水平、垂直的对齐组合，水平:left / center / right,垂直:top / middle / bottom，例如"bottom,right" | tile
EventLog | 事件日志 | 文件名，建议后缀是txt, 不必带路径，系统将自动在 BC 目录下创建. 该文件能自动记录本组件实例的所有事件, 用于程序调试. 注：正式运行时请不要使用，因为频繁读写磁盘会导致性能下降. | 无
FuncLog | 函数调用日志 | 文件名，建议后缀是txt, 不必带路径，系统将自动在 BC 目录下创建. 该文件能自动记录本组件实例被调用的所有函数, 用于程序调试. 注：正式运行时请不要使用，因为频繁读写磁盘会导致性能下降. | 无
FuncParaChars | 函数日志中参数最大字数 | 数字，当启用函数日志时，函数的参数最多保留字数. | 128
FuncReturnChars | 函数日志中返回值最大字数 | 数字，当启用函数日志时，函数的返回值最多保留字数. | 0

备注1: 所谓“默认值”就是在没有设定值的情况下，Tree自动采用的值.
备注2: 所谓“zip包中的BMP的URL”，写法例如: “http://..../abc.zip#pic1.bmp”
备注3: 上述URL为绝对URL或相对URL
2.关于图标

树控件的图标有多种方案。
方案一：默认图标方案
默认图标是根据上述创建参数中的NodeImage、LeafImage来定义的，树杈和树叶统一显示成2种图标。硕正套件已经内置了若干个图标，你可以从中选择。如果你想采用你自己定义的图标，须注意：
1.图片文件支持bmp、png、jpg、ico、gif、tif格式;
2.图片尺寸通常为16x16、24x24、32x32、64x64、128x128，最大不得超过128x128;
3.如果你希望图标在鼠标点中时的显示有所区别，应该将普通状态的图标和点中时的图标画在一起，左侧为普通状态的图标，右侧为鼠标点中时的图标。例如16x16的图标，尺寸应该是32x16了;
4.建议将图片资源打成zip包部署到服务器，并采用图片扩展URL书写，以提高性能;
方案二：独立图标方案
所谓独立图标方案是指每个树杈和树叶可以有不同的图标，这样每个节点的图标需要在数据XML中写明，请参见下面的“4.XML树”内容，当然也可以通过API函数SetXMLProp( )在js中动态设定;
图标的格式和注意事项请参见方案一，独立图标可以采用硕正套件内置的图标，也可以是自定义图标.
方案三：混合图标方案
即指定了默认图标，但又可以单独为某些节点指定图标.
3.函数

Supcan Tree的函数是通过插件/加载项的 func( string funcname, string paras ) 函数间接调用的，Supcan Tree组件的可用funcname及用途说明如下:

函数名 | 功能 | 参数 | 返回值
ReadXML 或Build | 读入构造树的XML/JSON | 参数1: XML/JSON的URL，或者直接是XML/JSON大串 参数2：可选，父节点的ID，表示插入到该节点下 | (无)
GetCurSel | 取得当前选中项的ID | (无) | ID
SetCurSel | 选中某项，当前焦点也相应转移 | ID | (无)
GetParent | 取得父节点的ID | ID | 父的ID
GetChild | 取得第一个子节点的ID | ID，空串表示根 | 子的ID
GetNextSibling | 取得下一个兄弟节点的ID | ID | 兄弟的ID
DeleteItem | 删除某项，包括其子孙 | ID，空串表示根(删除全部) | (无)
InsertItem | 插入一项 | 参数1: ID，须尚未存在 参数2(可选): PID，空串表示根节点 参数3(可选): text 参数4(可选): true/false, 表示在最后追加还是在最前面插入(默认true, 即追加) | true/false
Expand | 展开某项，包括其子孙 | ID | (无)
ExpandAll | 展开全部项，包括其子孙 | (无) | (无)
Collapse | 收拢某项 | ID | (无)
GetXMLProp | 取得XML某ID的属性值 | 参数1: ID 参数2: 可为PID、text、para、tip、img、textColor或任意属性 | 串
SetXMLProp | 设置XML某ID的属性值 | 参数1: ID 参数2: 可为PID、text、para、tip、img、textColor或任意属性 参数3: 值 注：参数2为PID表示更改父节点，作为参数1的ID须为树叶才能生效 | (无)
ChangeImage | 替换图标 | 参数1:树杈的图标，写法请参考创建参数"NodeImage"属性 参数2:树叶的图标，写法请参考创建参数"LeafImage"属性 | (无)
SetCheck | 设置Check | 参数1:ID 参数2:true/false 备注：仅用于创建参数Style含hasCheckbox | (无)
GetCheck | 取得Check | 参数:ID 备注：仅用于创建参数Style含hasCheckbox | true/false
GetCheckedIDs | 取得所有Check=true的ID | (无) 备注：仅用于创建参数Style含hasCheckbox | ID串, 以逗号分隔

注：函数中的ID参数是大小写敏感的!
此外，Tree还拥有一组和Treelist、Freeform完全一样的全局函数，请参见全局函数介绍。
4.XML树

Supcan Tree树是通过一个XML创建的，有二种XML格式可供选择。
第一种XML格式类似平面的结果集，由"PID"属性指定父节点，例如:

    <?xml version="1.0" encoding="utf-8"?>
    <Data>
    <items>
    　　<item ID="10" text="安装|Install" para="act.htm#Tag10" img="2"/>
    　　<item ID="20" text="硕正套件|Supcan RIA Suit" para="act.htm#Tag20"  img="12"/>
    　　<item ID="201" PID="20" text="语法|Gramma" para="act.htm#Tag201"/>
    　　<item ID="202" PID="20" text="函数|Function" para="act.htm#Tag202" LazyLoad="true"/>
    　　<item ID="203" PID="20" text="事件|Event" para="act.htm#Tag203"/>
    </items>
    </Data>

第二种XML格式本身就是一颗树，不需要单独指定"PID", 例如:

    <?xml version="1.0" encoding="utf-8"?>
    <Data>
    <items>
     <item ID="10" text="安装|Install" para="act.htm#Tag10" img="pack.zip#22.jpg"/>
     <item ID="20" text="硕正套件|Supcan RIA Suit" para="act.htm#Tag20">
      <item ID="201" text="语法|Gramma" para="act.htm#Tag201" LazyLoad="tree.aspx?id=201"/>
      <item ID="202" text="函数|Function" para="act.htm#Tag202"/>
      <item ID="203" text="事件|Event" para="act.htm#Tag203">
        <item ID="20301" text="OnReady" para="act.htm#Tag20301"/>
        <item ID="20302" text="OnEvent" para="act.htm#Tag20302"/>
      </item>
     </item>
    </items>
    </Data>

XML的属性规则如下:

属性 | 含义
ID | ID串，串可包含任意字符，ID必须唯一
PID | 从属的父ID
str 或 text | 显示的文字
tip | 鼠标滑过时的浮动Tip
img 或 image | 内置图标的数字(树叶图标需要加上10)，或自定义图标的URL，支持图片扩展URL. 注：如果是相对URL，是相对于当前XML文档，而非页面.
para | 可选参数
LazyLoad | 表示有子孙，且是在展开时动态加载的，有2种形式： 1.串"true", 表示通过"LazyLoad"事件触发(参见demo页); 2.是一个绝对或相对(相对于本XML)URL，用于自动加载，不触发事件.
check 或 checked | checkbox的值(true/false, 仅用于创建参数含hasCheckBox时)
textColor | 文字的颜色, 如"#FF0000"
其它任意属性 | 自定义属性，可通过GetXMLProp( )/SetXMLProp( )存取

如果text、tip需要有中英文切换功能，那么中英文之间以“|”分隔即可;
text也可以这样写: <item id="10">安装</item>
如果未定义text，那么将显示ID;
5.事件

Supcan Tree的OnEvent( id, Event, p1, p2, p3, p4 )事件含义及参数分别如下：