4.工具条功能号

通过上面的CallFunc函数可以调用工具条中的各个功能，各个工具条中的功能号规则如下：
1.主工具条 ( )：

功能号 | 含义 | CallFunc函数参数
102 | 新建报表 | 如果没有参数，表示直接打开对话框，就像鼠标点击工具条一样; 如果含有参数，则不打开对话框，而是直接建立新表，参数规则如下： name=[?]; rows=[?];cols=[?]; rowheight=[?]; colwidth=[?], 含义如下： name - 工作表名; rows/cols - 总行数/列数; rowheight/colwidth - 行高/列宽 示例： AF.func("callfunc", "102 \r\n name=我的工作表;rows=20;cols=8");
103 | 弹出打开报表文件的对话框 | 如果没有参数，就表示像鼠标点击工具条一样；如果有参数，那么参数格式为: type=[?];Dir=[?], 含义如下： type - xml 或 xlsx，表示对话框默认的文件类型; dir - 本地文件目录，表示对话框的初始目录定位
104 | 保存报表 | 文件名，用于强制指定文件名，文件类型可以是xml、zip
1074 | 报表另存为 | 如果没有参数，表示直接打开对话框，就像鼠标点击工具条一样; 如果含有参数，参数含义为本地全文件名，并且不打开对话框

105

转换输出.

如果没有参数，表示直接打开转换输出对话框，就像鼠标点击工具条一样; 如果含有参数，则不打开对话框，而是直接生成转换文件，并返回文件名，参数格式分数据文件和图像文件二种。

### 1.数据文件

参数格式为："Type=[?]; asData=[?]; includeHide=[?]; gridLine=[?];filename=[?];isForMobile=[?];isReturnContent=[?]"
Type是输出文档格式，有xlsx, xls, htm, doc, txt, xml, dif, rtf 这几种;
asData 为 true 表示输出纯数据，否则是包含了格式掩码的数据(比如含千位符)，默认false;
includeHide 表示是否包含隐藏行、隐藏列，默认false;
gridLine 表示是否是否显示表格线，仅用于XLS，默认false;
includeFormula 用于xlsx格式的转换，表示是否连公式一起转换, 默认是true.
isForMobile 用于Type="htm"，用于服务器专版中的报表转换输出的优化, 默认是false.
filename 要生成的全文件名，如果为空，则文件自动生成在硕正的临时目录下.
isReturnContent 如果为true, 表示函数返回的不是文件名，而是内容本身的字符串，常用于Type="htm"、服务器专版中的报表转换输出的优化, 默认是false.

### 2.图像文件

参数格式为："Type=[?]; Scale=[?]; Precision=[?];filename=[?]"
Type是输出文档格式，有pdf, jpg, bmp, gif, png, tif 这6种，默认是jpg;
Scale是打印比例，范围是10 到 400，默认100。对于PDF而言，Scale越大越清晰，例如300表示在300%的显示比例下仍很清晰;
Precision是JPG精度，仅对JPG有效，精度范围1-100(默认85)，越接近100越清晰，但文件尺寸越大.
filename 要生成的全文件名，如果为空，则文件自动生成在硕正的临时目录下.
函数调用举例如下:
var filename = func("callfunc", "105\r\nType=jpg; Scale=100; Precision=85");
返回值均为输出文件名(含路径的全文件名)，由于图像文件是分页输出的，所以象jpg、bmp这些格式可能会有多个文件名(PDF除外)，文件名间以回车分隔，空串表示转换过程有错误.

100 | 报表属性设置 |
189 | 关于 |
20 | 20 | 复制 |
31 | 剪切 |
32 | 34 | 粘贴格式和文字 |
35 | 仅粘贴文字 |
106 | Undo |
107 | 427 | 查找 |
426 | 替换 |

2.打印工具条 ( )：

功能号 | 含义 | CallFunc函数参数
11 | 11 | 打印报表 |
318 | 转换为PDF或图片文件 | 请参考功能号105(转换输出)
216 | 打印设置 |
18 | 打印预览 |

3.常用功能工具条 ( )：

功能号 | 含义 | CallFunc函数参数
110 | 单元合并 |
162 | 求和 |
164 | 计算器 |
163 | 163 | 重新计算 |
260 | 除数据源外，重新计算 |
630 | 仅计算当前工作表 |
140 | 140 | 打开数据源对话框 |
395 | 数据分组汇总 |
520 | 交叉表 |
143 | 清理从数据源填入的数据 | 如果参数是 true, 表示同时清理表头的信息
717 | 全屏显示 | 0-自动，1-退出全屏, 2-进入全屏
4 | 折叠/展开工具条 |

4.工具箱工具条 ( )：

功能号 | 含义 | CallFunc函数参数
301 | 打开工具箱 | 参数可以为1、2、3、4，分别表示将当前页定位在属性、计算公式、数据源、上报的指标库页
2 | 2 | 单元格显示计算公式 |
64 | 单元格显示计算结果 |
25 | 设置数据验证 |
50 | 执行数据验证 | 参数如下： 无参数: 验证全部工作表; -1: 仅验证当前工作表; 0 到 n，或工作表名称: 验证指定名称或次序的工作表. 返回1表示通过验证, 0表示未通过，空串表示工作表不存在

112

添加文本框

如果没有参数，就表示像鼠标点击工具条一样; 如果含有参数，则参数规则如下:
x=[?];y=[?];width=[?];height=[?]; alias=[?];text=[?] 或
x1=[?];y1=[?];x2=[?];y2=[?]; alias=[?];text=[?] 或
其中的 x / y / x1 / x2 / y1 / y2 / width / height为坐标参数，alias表示别名，text表示文本框的文字(也可以是计算函数)。
坐标参数含义及可用值语法为：
x / y 或 x1 / y1 - 左上角坐标, 可以是像素数，或单元格名，表示位于该单元格的左上角位置，此外，如果是串"drag", 表示位置不固定，并将随即出现拖拽中的鼠标，效果如同点击该按钮;
x2 / y2 - 右下角坐标, 可以是像素数，或单元格名，表示位于该单元格的右下角位置;
width / height - 宽度和高度, 像素数
示例：
AF.func("callfunc", "112 \r\n x=drag; text=测试");

192 | 192 | 添加图片 | 同上，但有三个跟图片相关的参数：URL、IsSaveURLOnly、MaxSize, 其含义如下： URL - 图片的URL(也可以是本地的全文件名)； IsSaveURLOnly - 是否仅仅将图片的URL保存入到报表，默认是false； MaxSize - 限定图片尺寸，格式为宽度和高度的像素数，逗号分隔。当图片的宽度或高度超过时，将自动转换到该尺寸，以减小报表文件的尺寸，仅用于IsSaveURLOnly=false时。当设置了maxSize后，图片将按比例缩放，x2、y2、width、height参数可以省略； 示例： AF.func("callfunc", "192 \r\n x=drag; URL=../mylib/demo.jpg; maxSize=400,400");
17 | 添加图片(打开对话框) |
683 | 从剪切板粘贴图片 |
144 | 添加线条 | 同上，但有二个跟线条相关的参数：color、thick, 其含义如下： thick - 线条粗细，像素数，默认是1； color - 线条颜色；
478 | 添加统计图 |
382 | 添加树列表 | 同上，但有三个跟树列表相关的参数：URL、isSaveURLOnly、isBackGround, 其含义如下： URL - 树列表的URL(也可以直接是XML大串); isSaveURLOnly - true/false, 分别表示仅将URL保存到报表/把树列表的XML串储存到报表中, 默认是true； isBackGround - true/false, 分别表示树列表采用原始背景效果/采用白色背景， 默认是true.
274 | 274 | 格式刷 |
122 | 表格线橡皮 |

5.不在工具条上的其它功能号：

功能号 | 含义 | CallFunc函数参数
404 | 自动调整行高，使文字能全部显示 |
405 | 自动调整列宽，使文字能全部显示 |
446 | 合并相同内容行 | 参数为列号，列号从0开始
0 | 计算消息窗的打开方式 | 0－始终不打开；1-遇到计算有错误就打开
900 | 取得当前报表已打印的次数，返回值其实是整数 |
108 | 切换为分页显示 |
109 | 切换为常规显示 |
15 | 切换显示比例 | 参数可为20、50、80、100、150、200
309 | 切换上报模式时的普通输入和设定输入顺序. |

5.自定义工具条

Supcan Report的工具条是可以自定义的，请在\Documents and Settings\用户名\BC 目录下的相应版本目录中找到如下文件：
FormRes.zip
将其解开，会发现有一个名为ToolBar.xml的文件，该XML就是默认工具条的配置文件，可查看该XML，工具条的秘密基本上都在这里了。
您也可以自己制作一个xml，连同bmp图片文件一起打成zip包，然后在页面控件“CtlPara”中定义“UserRebar”(该zip包所在的URL，请参见前面的“语法”部分)、在“Rebar”中确定要显示的子工具条即可实现自定义工具条。本demo包中“几种展现方式”页的第五个例子就是自定义工具条的详细演示。
子工具条<Toolbar ...>的可用属性及其含义如下：

属性名 | 含义
name | 子工具条名称
imageList | 按钮的图片表，是BMP格式的ImageList，该图片文件须位于同一zip包内.
imageHeight | 图片高度，单位：像素数，通常为16、24、32、48，单幅图片的宽度必须和高度一致.
imageTransparentColor | 图片需要转换为透明的背景色.
textAlign | 按钮中的文字相对于图片的位置，可为“right”、“bottom”，没有定义就表示仅显示图片、不显示文字。默认工具条就没有显示文字。
textDistance | 按钮中文字和图片的最小间隔，单位：像素数，默认：3.
textColor | 文字颜色，默认：黑色.

子工具条内各个按钮<item ...>的可用属性及其含义如下：

属性名 | 含义
id | 功能号，3000以内是内部保留号，每个功能号对应了报表中固定的功能(可参见前面的“工具条功能号”)；3000以上(包括3000)表示自定义功能号；0表示分隔条.
imageIndex | 表示在Imagelist内的单幅图片的位置，从0开始计数.
tip | 鼠标滑过时的帮助文字、和下拉菜单的文字，如果需要支持中英文双语，则以“|”分隔中英文.
text | 显示在按钮上的文字、或下拉菜单的文字，如果需要支持中英文双语，则以“|”分隔中英文.
detail | 下拉菜单功能的具体说明，当菜单下拉时，会在菜单下方弹出该说明文字，则以“|”分隔中英文.
defaultId | 仅用于有子树(需要下拉)的按钮，表示鼠标点击在按钮左侧非下拉区域时，默认执行的功能，该功能通常可为子树中的第一个功能；如果没有定义defaultId，那么点击在整个按钮均为下拉.
style | button - 普通平坦透明按钮 checkbutton - 按钮有凹陷显示、普通显示2种状态，类似于Checkbox.

自定义工具条注意事项：
1.通过了解默认工具条的XML配置文件，会发现其中共定义了7个子工具条：Main, Print, Form, Font, Property, Text，除了“Font”和“Text”是固定的、不可配置，其它子工具条均是可配置的;
2.自定义功能(即功能号在3000以上的)一律以OnEvent("Toolbar", ..)事件形式抛给页面、交由页面处理的；
3.须将XML文件和BMP打成一个zip包，XML文件的文件名必须为Toolbar.XML；
4.自定义工具条中须包含“关于”功能(功能号:189)，否则，Supcan Report会自动在第一个子工具条后安插一个“关于”功能；
5.一旦启用自定义的zip包，原默认zip中的同名子工具条将被替换，未被同名的子工具条仍然有效；
6.一旦启用自定义的zip包，“CtlPara”中的“Rebar”串的取值范围可包括自定义包、原默认包的的子工具条名；
7.自定义工具条的作用范围仅为当前Report实例；
8.函数 SetToolBarItemStatus / GetToolBarItemStatus 可以动态更改某些状态；
6.自定义菜单

自定义菜单和Treelist中的自定义菜单完全一致，请参考Treelist的8.自定义菜单.
7.自定义函数

在报表的集成开发中，免不了会需要自定义一些业务函数，以简化开发。
自定义函数对于开发者而言，是一种抽象、归纳数据逻辑的非常好的手段。最终使用者是否能接纳自定义函数，关键要看自定义函数能否有诸如向导式帮助、实例书写参考等等方便输入的功能，如果这些问题解决不好，用户很有可能产生畏惧心理。
硕正报表自身已经有向导式帮助、实例书写参考等功能，只要求开发者以如下的XML格式、并通过调用AddUserFunctions( )函数，将自定义函数告诉控件即可：

    <?xml version="1.0" encoding="UTF-8"?">
    <Category name="函数分类1">
     <function name="函数名" >
      <usage>用途说明</usage>
      <detail>更详细的说明，可选</detail>
      <para>参数1，可选</para>
      <para>参数2，以此类推，可选</para>
      <returnDatatype>返回值的数据类型，如int、double等，可选</returnDatatype>
      <example>示例说明，可选</example>
     </function>
     <function name="函数名" >
      ...
     </function>
     ...

     <!-- 嵌套分类 -->
     <Category name="函数分类11">
      <function name="函数名" >
       ...
      </function>
     </Category>
    </Category>
    <Category name="函数分类2">
     ...
    </Category>

通过分析上述XML，可见XML文档中允许多个函数分类(即Category)，每个类别中允许有多个函数，并支持子类别的层层嵌套。
一旦控件得到该函数声明XML，就会立即建立起函数的语法词法规则、在工具箱中展示这些函数、并能提供函数的即时输入帮助。
此外，开发者也可以将函数分散在多个XML文件中，可以分多次调用AddUserFunctions( )，分别传入不同的XML文档。
总之，自定义函数功能的价值在于让最终用户方便地使用业务函数：在开发者设定的范围内，指导最终用户正确地去书写、调用，以省去很多维护、定制开发的工作量。
7.1 简单应用
自定义函数最终怎么完成计算？ 控件反向调用js!
例如，XML中声明了如下函数名:

     <function name="balance" >
      <para>编码，可选</para>
      <para>月份，可选</para>
      <returnDatatype>double</returnDatatype>
     </function>

那么在页面中必须要有同名、大小写一致的js函数:

     function balance(code, mon)
     {
       var d;
       ..(略)
       return d;
     }

如果函数在处理过程中需要调用后端数据库信息，那么可以通过Ajax调用(必须是"同步")后端服务方式实现.
可见普通的自定义函数应用场景，只不过是使某些固定的js()函数的调用变得方便而已，因为自定义函数最终仍由页面的同名js函数负责执行，这在“自定义函数”演示页中已经剖析殆尽。
7.2 高级应用
7.2.1 SetBatchFunctionURL( )
有一种极端的应用场景是：用户设计的报表很大，引用自定义函数会达数百处甚至上千处，如果按照上面“6.1.简单应用”的实现方式，并且假设自定义函数都是需要通过Ajax来完成计算，那么，最终会导致什么后果？想必您应该知道了!
为了解决成百上千次的Http请求/响应带来的网络性能瓶颈，硕正报表提供了一个批处理解决方案，方案说明如下：
1.通过js函数 SetBatchFunctionURL( ) 设置后端批处理函数的URL;
2.开发者需要开发后端的Java/Asp.Net批处理响应程序.
一旦通过SetBatchFunctionURL( )设置了后端批处理URL地址，报表在计算过程中将不再调用页面的同名自定义函数，转而采用分批的方式将函数直接交由后端执行， 分批发送的是Http POST，并采用如下的XML格式:

    <Root>
     <Functions addition="附加串" >
      <!-- 第一个 -->
      <Function name="函数名">
      </Function>
      <!-- 第二个 -->
      <Function name="函数名">
       <Para>参数</Para>
       <Para>参数</Para>
      </Function>
      <!-- 第三个 -->
      <Function name="函数名">
       <Para>参数</Para>
      </Function>
      <!-- 第 n 个等等 -->
      ...
     </Functions>
    </Root>

其中的“函数名”、“参数”表示真实的函数名、参数。“附加串”是SetBatchFunctionURL()函数中的附加参数(相当于附言，任意串，请参考SetBatchFunctionURL()函数帮助)。
后端的服务程序需要解析该XML，并完成这些函数的计算，最终按如下XML格式作为响应返回:

    <Root>
     <Functions>
      <Function>返回值</Function>
      <Function>返回值</Function>
      <Function>返回值</Function>
      <Function>
       <fault>
        <faultcode>错误代码</faultcode>
         <faultstring>错误</faultstring>
         <detail>详细描述</detail>
         <reason>错误原因</reason>
         <faultactor>错误角色</faultactor>
       </fault>
      </Function>
      <Function>返回值</Function>
      ...
     </Functions>
    </Root>

备注1: <Function>的顺序必须和前面请求中的XML保持一致;
备注2: <Function>的返回值，硕正默认是把它当作数值型的，如果您希望返回 string 型，必须在串的前后加单引号;
备注3: 其中<fault> ... </fault>表示某个函数的服务器端错误信息;
7.2.2 前后端混合计算
有时候并不是所有自定义函数都必须推送到后端计算，可能有部分函数需要在本地页面中计算，那么只要修改XML的定义，增加<RunAt>内容：

    <?xml version="1.0" encoding="UTF-8"?">
    <Category name="函数分类">
     <function name="函数名" >
      <usage>用途说明</usage>
      <detail>更详细的说明，可选</detail>
      <runAt>Local</runAt>
     ...

凡是runAt被定义为 "Local"(或Client)的函数，都不会被发送到后端，而是简单地在客户端计算. runAt的默认值是"Server"，即后端计算.
7.3 参数输入向导
硕正报表从1.0.64.0开始，增加了函数的向导式输入功能(输入框左侧的f(x)小按钮)：
为了方便自定义函数的输入，我们对自定义函数的XML规范作了扩充，使得参数在输入时能支持下拉选择，例如下图所示的效果：
扩充后的自定义函数XML规范增加了如下内容：
1.XML增加了<Droplists>下拉资源库节点
XML中须增加<Droplists>节点，<Droplists>语法和硕正Treelist树列表、Freeform自由表头中的<Droplists>完全一致，请参见其XML文档规范，也可以参考自定义函数演示页中的XML例子.
2.参数<Para>增加下拉相关属性
增加3个属性, 例如<Para dataType="?" edittype="?" droplistID="?" >参数</Para>，其含义和可用值如下：
datatype - 可以为int, string;
edittype - 可以为droplist、editAbleDroplist、dropTreelist、editAbleDropTreelist，含义请参考树列表或自由表头文档资料;
droplistId - 指向下拉资源库的Id;
如果您开发过Treelist或freeform，会发现该规则很简单，相当于把Treelist、freeform的下拉语法直接搬过来了.