<自用笔记>PB数据窗口控件之事件

【事件】

◆Clicked
鼠标左键在数据窗口控件上任意位置单击时触发该事件。该事件中有4个参数，可以在脚本中直接使用。
xpos：表示和数据窗口最左侧的距离的整数。
ypos：表示和数据窗口最上部的距离的整数，不包括标题条。
row：表示用户所单击的行号的long型数。
dwo：用户单击对象，是DWObject类型。
在该事件的脚本中使用这些参数，可以给用户一些提示信息或者获取用户单击内容的信息。
返回值：0表示继续处理，这是缺省值。1表示停止处理。
*当选择和当前行不同的数据行时可以触发ItemFocusChanged和RowFocusChanged事件，当单击当前行的其他字段时可以触发ItemFocusChanged事件。DoubleClicked事件也可以触发该Clicked事件。

◆DBError
在数据窗口控件中发生数据库错误时触发该事件。该事件有以下参数。
SQLdbcode：long类型的错误代码，具体含义由DBMS指定。当DBMS没有指定错误代码时，SQLdbcode提供4个错误代码，-1表示事务对象参数错误而不能联结到数据库，-2表示不能联结到数据库，-3表示因为其他用户的修改导致用来进行检索或修改的键值在数据库中已经不存在而产生错误，-4表示向数据库中写blob对象时失败。
SQLerrtext：string类型，数据库指定的错误信息。
SQLsyntax：string类型，当错误发生时，发送到数据库的SQL语句。
buffer：DWBuffer枚举型，表示导致错误的数据所在的缓冲区。
row：long类型，导致错误的数据的行号。
返回值：可以用return语句任意指定返回什么数据。有特定含义的返回值是0和1。0表示显示错误信息，1表示不显示错误信息。

◆DoubleClicked
鼠标左键在数据窗口控件中双击时触发该事件。该事件中的4个参数和Clicked事件中的名称及含义完全相同，也可以直接在该事件的脚本中直接使用。
该事件的返回值可以用return指定。有特殊函数的返回值是0，表示继续处理。

◆EditChanged
在数据窗口控件的编辑框中每次按钮都触发该事件。一般很少在该事件下编写脚本。该事件提供三个参数。
row：long类型，当前编辑的行号。
dwo：DWObject类型，正在编辑的对象。
data：String类型，当前编辑框中的内容。
返回值：可以用return指定任意返回值，0表示继续处理。
*每次编辑时触发

◆Error
当数据窗口对象中的数据或者表达式错误时触发该事件，在分布式系统中联结发生错误时也会触发该事件。和DBError事件不同的是，该事件在没有和数据库交互时就有可能触发，而DBError事件触发时肯定和数据库发生了交互。通常在该事件中编写脚本，提供对错误的处理。该事件提供了很多参数。
errornumber：unsigned integer类型，由PowerBuilder指定的错误代码号。
errortext：string类型，由PowerBuilder指定的错误信息。
errorwindowmenu：string类型，造成错误的脚本所在对象的父对象的名称。
errorobject：string类型，造成错误的脚本所在的对象的名称。
errorscript：string类型，造成错误的语句所在的脚本的全部内容。
errorline：unsigned integer类型，造成错误的语句在其脚本中所占的行号。
action：在Error事件下的代码执行完后，该参数取值由脚本设定。可以指定的值有：ExceptionFail!表示错误处理失败（执行该值有可能触发应用的SystemError事件）；ExceptionIgnore!表示忽略错误继续执行（要谨慎使用该取值，因为忽略错误有可能将再次导致其他错误）；ExceptionRetry值只能用于OLE，对于数据窗口控件，没有该取值，该取值表示再次执行刚才造成错误的功能；ExceptionSubstituteReturnValue!表示使用参数returnvalue的返回值，而不是返回OLE服务器或数据窗口控件的错误代码，并且取消错误状态。
returnvalue：当Action指定为ExceptionSubstituteReturnValue!时返回该参数的取值。
*对于数据窗口控件来说，如果在运算数据或属性表达式时发生了错误，将进行如下的错误处理过程：
a.触发Error事件；
b.如果Error事件中没有脚本或者Action变量设置成ExceptionFail!，则触发应用的SystemError事件；
c.如果SystemError事件下也没有脚本，便会发生应用程序错误，然后终止应用程序。
所以，在该事件或者应用的SystemError事件下应该编写脚本。这样才不至于退出应用程序，使用户没有处理的机会，甚至录入了半天的数据连个保存的机会也没有了。
返回值：该事件没有返回值，也不在该事件中使用return语句。

◆ItemChanged
当某单元（行和列的交叉点叫做单元）编辑后(内容改变)，光标要离开时触发该事件，如使用了Enter按钮、单击了Tab按钮、使用了光标键、在其他字段上单击了鼠标左键等。当编辑完一个单元的内容而没有离开该单元，这时数据窗口失去焦点，这种情况不会触发该事件（所以在LoseFocus事件中要使用函数AcceptText）。三个参数row、dwo和data的含义和EditChanged事件的三个参数完全相同。
返回值：可以使用return语句返回任意值。0表示接受刚刚修改的数据，该值是缺省值；1表示放弃刚才的修改，不允许焦点离开；2表示放弃刚才的修改，允许焦点离开。
*编辑框内容有变化并离开此编辑框时触发；注意：当editchanged事件下有代码，编辑框内容有变化且离开此编辑框时，不会触发此事件

◆ItemError
当某单元被编辑后光标要离开时，如果单元中的新数据不能通过有效性校验，则触发该事件。(同ItemChanged：当编辑完一个单元的内容而没有离开该单元，这时数据窗口失去焦点，这种情况不会触发该事件)该事件在ItemChanged事件之前触发，该事件触发就不能再触发ItemChanged事件了。该事件中的三个参数和ItemChanged事件中的三个参数完全相同。
返回值：可以使用return语句返回任意数值， 0表示放弃修改的数据，并显示错误信息，焦点不离开该单元，该取值是缺省值；1表示放弃修改的数据但不显示错误信息提示，焦点不离开该单元；2表示接受刚刚修改的错误数据；3表示放弃刚刚修改的数据，并且焦点不离开该单元。

◆ItemFocusChanged
当焦点离开某单元时触发该事件(不管内容有没有改变)。该事件提供了row和dwo两个参数，含义和前面介绍的完全相同。可以使用return语句返回任意数值，0表示继续处理。
*不管编辑框中的内容有没有改变，离开编辑框时触发该事件，注意：当离开数据窗口时不触发

◆PrintEnd
当打印工作完成时触发该事件。参数PagesPrinted可以在脚本中直接使用，是一个long类型的变量，表示已经被打印的页数。

◆PrintPage
在数据窗口每页进行打印格式处理之前触发该事件。参数Copy和PageNumber在脚本中可以直接使用，表示该页要打印的份数和当前页的页号。返回值0表示不要跳过当前页，1表示跳过当前页。一般在该事件下编写脚本显示打印进度信息，例如：
st_1.text="正在打印第"+String(pageNumber)+ "页……"
也可以在该事件中决定是否真正要打印该页。例如，下面的脚本只打印偶数页码的页面：
If Mod(pagenumber,2) = 0 Then
return 0
Else
return 1
End If

◆PrintStart
数据窗口打印开始时触发该事件。该事件中的参数PagesMax是一个long型变量，表示将要被打印的总页数（不包括跳过的页）。返回0表示继续处理。

◆RetrieveEnd
当数据窗口检索完毕时触发该事件。参数rowcount是一个long型变量，表示检索完后检索到的记录数。

◆RetrieveRow
每检索到一条记录时都触发该事件。参数row是long类型变量，记录当前检索到的数据的序号。返回值0表示继续检索，1表示停止检索。检索大量数据之前可以设置中断标志，让用户在检索过程中可以停止检索。

◆RetrieveStart
当数据窗口的检索操作将要开始时触发该事件，该事件中没有参数。返回值0表示继续执行，该值是缺省值，1表示不执行检索，2表示在检索之前不清除数据行和缓存区。通常不在该事件下编写脚本，即使编写脚本，一般也是利用返回值2的特性来控制检索操作不清除缓存区，这样可以将检索到的数据添加到数据窗口中，并且在数据窗口中保留检索之前的数据。

◆RowFocusChanged
当前行改变时触发该事件。CurrentRow参数是一个long类型变量，保存当前记录号。该事件下的典型编程是修改当前行标识，将当前行明显地标识出来，可以让用户清楚地知道要对哪行进行操作，在该事件和其他事件的配合下共同修改当前行标识。
*不管内容有没有改变，当前行改变时触发；在离开数据窗口时不触发
*RowFocusChanging：当前行改变前触发；参数currentrow触发前所在行，newrow触发后当前行；rowfocuschanged的currentrow等于rowfocuschanging的newrow

◆ScrollHorizontal
当使用光标键、Tab按钮、滚动条等等在数据窗口中进行水平滚动时触发该事件。很少在该事件上编写脚本。

◆ScrollVertical
当在数据窗口中使用光标键、滚动条、Tab键等进行上下滚动时触发该事件。通常在该事件中编写脚本来改变当前行。因为当上下滚动数据窗口时，如果当前行不在当前显示的区域内，则容易给用户造成错觉，可以在该事件中编写脚本将当前页面的第一行数据设置为当前行。使用Describe和Evaluate函数可以实现该功能

◆SQLPreview
当执行函数Retrieve、ReselectRow和Update时，SQL语句要提交到DBMS，这时触发该事件。该事件的参数比较复杂。
request：取值为PreviewFunctionReselectRow!、PreviewFunctionRetrieve! 或PreviewFunctionUpdate!分别代表触发该事件的函数是ReselectRow、Retrieve和Update。 SQLtype：引起该事件的SQL语句类型。取值为PreviewDelete!、PreviewInsert!、PreviewSelect!、PreviewUpdate! 分别表示是Delete 、Insert、Select、Update语句。
SQLsyntax：string类型，取值为提交到DBMS的SQL语句。
buffer：当前SQL语句所涉及到的数据所在的缓存区，取值为枚举型，Delete!、Filter!、Primary!分别表示删除缓存区、过滤缓存区和主缓存区。
row：long类型变量，表示该事件中涉及到的记录数。
返回值0表示继续处理，1表示停止处理，2表示处理下一个SQL请求。

◆UpdateEnd
当从数据窗口控件发送来的对数据库的修改都完成后触发该事件。该事件的三个参数RowsInserted、RowsUpdated、RowsDeleted都是long类型的变量，分别表示插入、修改和删除的记录数。

◆UpdateStart
在调用了update函数之后、开始修改之前触发该事件，该事件没有参数。返回值0表示继续处理，1表示停止修改。

◆LoseFocus
数据窗口失去焦点时触发。
该事件中编写脚本，主要是保证用户在数据窗口中最后输入的内容不丢失。数据窗口中的输入内容只有当焦点改变时才真正转交给数据窗口，否则只是保存数据窗口的编辑控件。脚本比较简单：this.AcceptText()
*GetFocus：数据窗口得到焦点时触发。