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取得父节点的IDID父的ID
GetChild取得第一个子节点的IDID，空串表示根子的ID
GetNextSibling取得下一个兄弟节点的IDID兄弟的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的属性规则如下:
属性含义
IDID串，串可包含任意字符，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 或 checkedcheckbox的值(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 )事件含义及参数分别如下：