二十一、其他函数

二十一、其他函数

1、Beep()

功  能：响铃n次（n超过10时只响10次）。

语  法：Beep ( n )

参  数：n：数值类型，指定需要的响铃次数。如果n的值大于10，那么计算机只响铃10次。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。如果参数n的值为NULL，Beep()函数返回NULL。

示  例：This statement causes the computer to beep five times:

Beep(5)

 

2、ChooseColor()

功  能：显示标准的颜色选择对话框，供用户选择颜色。

语  法：ChooseColor (color {,cusromcolors[]})

参  数：color：Long类型，保存用户在对话框中所选择的颜色；

customcolors：Long类型，可选项，用于向选择颜色对话框传递定制颜色和接收用户选择的定制颜色。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。当用户选择了”取消”按钮或直接关闭对话框，函数返回0。

示  例：This example displays the color selection dialog box with a base color of red and with two different custom colors defined:

long  red, green, blue

long custom[ ]

integer li_color

red = 255

custom[1]=rgb(red, 200, blue)

custom[2]=8344736

li_color = ChooseColor( red, custom [ ] )

 

3、ClassName()

功  能：确定指定变量的类（数据类型）。

语  法：ClassName(variable)

参  数：variable：指定要确定其数据类型的变量。

返回值：String。函数执行成功时返回指定变量的数据类型，发生错误时返回空字符串。如果参数variable的值为NULL，ClassName()函数返回NULL。

用  法：需要注意的是，ClassName()函数不能确定枚举类型变量的类型，此时，ClassName()函数返回空字符串（""）。

示  例：If gd_double is a global double variable, ClassName sets varname to double:

string varname

varname = ClassName(gd_double)

 

4、DebugBreak()

功  能：暂停程序执行，打开调试器，进入调试模式。

语  法：DebugBreak ( )

返回值：无。

用  法：DebugBreak()函数可以帮助你调试应用程序。如果你希望应用程序执行某条语句后暂停执行，然后进入调试模式，那么可以在该语句后面放上DebugBreak()函数，应用程序执行到DebugBreak()函数后，打开Debug（调试）窗口，并在其中显示当前上下文信息。这种方式实现了应用程序在PowerBuilder开发环境中的即时调试功能。

示  例：This statement tests whether a variable is NULL and opens the Debug window if it is:

IF IsNull(auo_ext) THEN DebugBreak()

 

5、GetFolder()

功  能：显示文件夹选择对话框。

语  法：GetFolder (title , director )

参  数：title：String类型，指定文件夹选择框的标题；

        directory：String类型，文件夹的路径，即指定显示哪个文件夹下的子文件夹，又用于保存用户最终选择的文件夹的路径。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。当用户选择了”取消”按钮或直接关闭对话框，函数返回0。

示  例：This example displays the folder contents of the Sybase directory in a folder selection dialog box. The string passed in the title argument displays above the tree view:

string ls_path = "d:\program files\sybase"

integer li_result

li_result = GetFolder( "my targets", ls_path )

sle_1.text=ls_path 

// puts the user-selected path in a SingleLineEdit box.

 

6、IntHigh()

功  能：得到Long型值的高位字。

语  法：IntHigh ( long )

参  数：long：long型值或变量。

返回值：Integer。函数执行成功时返回参数long的高位字，发生错误时返回-1。如果参数long的值为NULL，

IntHigh()函数返回NULL。

用  法：IntHigh()函数通常用于分解外部C或C++语言函数的返回值和Windows消息。

示  例：These statements decode a long value LValue into its low and high integers:

integer nLow, nHigh

long LValue = 274489

nLow = IntLow (LValue)  //The Low Integer is 12345.

nHigh = IntHigh(LValue) //The High Integer is 4.

 

7、IntLow()

功  能：得到Long型值的低位字。

语  法：IntLow ( long )

参  数：long：long型值或变量。

返回值：Integer。函数执行成功时返回参数long的低位字，发生错误时返回-1。如果参数long的值为NULL，IntLow()函数返回NULL。

用  法：IntLow()函数通常用于分解外部C或C++语言函数的返回值和Windows消息。示例请参看IntHigh()函数。

示  例：These statements decode a long value LValue into its low and high integers:

integer nLow, nHigh

long LValue = 12345

nLow = IntLow(LValue)   //The Low Integer is 12345.

nHigh = IntHigh(LValue) //The High Integer is 0.

 

8、IsValid()

功  能：检查对象变量是否已经实例化，即实例变量的值是否是个有效的对象句柄。

语  法：IsValid ( objectname )

参  数：objectname：要检测的对象名。

返回值：Boolean。如果指定对象已经创建了对象实例，那么IsValid()函数返回TRUE，否则返回FALSE。如果参数objectname的值为NULL，IsValid()函数返回NULL。

示  例：This statement determines whether the window w_emp is open and if it is not, opens it:

IF IsValid(w_emp) = FALSE THEN Open(w_emp)

 

This example returns -1 because the IsValid function returns FALSE. Although the objectvariable argument is a valid string, it is not an instantiated object. The IsValid method would return TRUE only if la_value was an instantiated object:

any la_value

la_value = "I'm a string"

IF NOT IsValid(la_value) THEN return -1

 

9、KeyDown()

功  能：检查用户是否按了键盘上指定的键。

语  法：KeyDown ( keycode )

参  数： keycode：KeyCode枚举类型或integer类型，指明要检测的按键或某个键的ASCII值。

返回值：Boolean。如果用户按了keycode参数指定的按键，函数返回TRUE，否则返回FALSE。如果参数

keycode的值为NULL，KeyDown()函数返回NULL。

用  法：KeyDown()函数通常在某个事件的事件处理程序中调用，它并不指明用户键入了哪个字符，而是说明当前事件（即事件处理程序中调用KeyDown()函数的事件）发生时用户正按着哪个按键。

一般来说，应用程序在窗口的Key事件或控件的按键事件中调用KeyDown()函数，以检测用户是否按了某个特殊键。对控件来说，PowerBuilder没有定义预定义的Key事件，这也没有关系，如果在控件得到焦点后希望应用程序检测用户的按键，只要对该控件定义一个用户事件，并把pbm_keydown （其它控件）或pbm_dwnkey（数据窗口控件）映射到该用户事件上即可。

示  例：The following code checks whether the user pressed the F1 key or the Ctrl key and executes some statements appropriate to the key pressed:

IF KeyDown(KeyF1!) THEN

. . . // Statements for the F1 key

ELSEIF KeyDown(KeyControl!) THEN

. . . // Statements for the CTRL key

END IF

 

This statement tests whether the user pressed Tab, Enter, or any of the scrolling keys:

IF (KeyDown(KeyTab!) OR KeyDown(KeyEnter!) OR &

KeyDown(KeyDownArrow!) OR KeyDown(KeyUpArrow!) &

OR KeyDown(KeyPageDown!) OR KeyDown(KeyPageUp!))&

THEN ...

 

This statement tests whether the user pressed the A key (ASCII value 65):

IF KeyDown(65) THEN ...

This statement tests whether the user pressed the Shift key and the A key:

IF KeyDown(65) AND KeyDown(KeyShift!) THEN ...

This statement in a Clicked event checks whether the Shift is also pressed:

IF KeyDown(KeyShift!) THEN ...

 

10、MessageBox()

功  能：显示一个消息对话框。

语  法：MessageBox(title,text{,icon{,button{,default}}})

参  数：title：string类型，指定消息对话框的标题；

text：指定消息对话框中显示的消息，该参数可以是数值数据类型、字符串或boolean值；

icon：Icon枚举类型，可选项，指定要在该对话框左侧显示的图标；

button：Button枚举类型，可选项，指定显示在该对话框底部的按钮；

default：数值型，可选项，指定作为缺省按钮的按钮编号，按钮编号自左向右依次计数，缺省值为1，如果该参数指定的编号超过了显示的按钮个数，那么MessageBox()函数将使用缺省值。

返回值：Integer。函数执行成功时返回用户选择的按钮编号（例如1、2、3等），发生错误时返回-1。如果任何参数的值为NULL，MessageBox()函数返回NULL。

用  法：当你的应用程序需要显示一段简短信息（比如显示出错、警告等信息）时，没有必要自己从头创建窗口、安排控件，使用MessageBox()函数既简单又方便。用户只有响应该窗口后，程序才能继续运行下去。

MessageBox()函数的icon参数指定显示在窗口中的图标，它是枚举类型，可能取值为：Information!， StopSign!，Exclamation!，Question!，None!。其中Information!是Icon参数的缺省值。Button参数指定在窗口中显示哪些按钮，有效取值为：取值中文Windows 下显示OK!“确定”按钮，OKCancel!“确定”、“取消”按钮，YesNo!“是”、“否”按钮，YesNoCancel!“是”、“否”、“取消”按钮，RetryCancel!“重试”、“取消”按钮AbortRetryIgnore!，“终止”、“重试”、“忽略”按钮。

示  例：This statement displays a MessageBox with the title Greeting, the text Hello User, the default icon (Information!), and the default button (the OK button):

MessageBox("Greeting", "Hello User")

The following statements display a MessageBox titled Result and containing the result of a function, the Exclamation icon, and the OK and Cancel buttons (the Cancel button is the default):

integer Net

long Distance = 3.457

Net = MessageBox("Result", Abs(Distance),Exclamation!, OKCancel!, 2)

IF Net = 1 THEN

... // Process OK.

ELSE

... // Process CANCEL.

END IF

 

11、PixelsToUnits()

功  能：将像素值转换为PowerBuilder单位PBU。

语  法：PixelsToUnits ( pixels, type )

参  数：pixels：integer类型，指定要转换为PowerBuilder单位的像素数；

type：ConvertType枚举类型，指定按哪个方向进行转换。有效取值为：

XPixelsToUnits! -- 按水平方向转换像素；

YPixelsToUnits! -- 按垂直方向转换像素。

返回值：Integer。函数执行成功时返回pixels参数指定像素数按指定方向转换成的PowerBuilder单位数，发生错误时返回-1。如果任何参数的值为NULL，PixelsToUnits()函数返回NULL。

用  法：窗口中水平方向和垂直方向相同的像素数表示的距离并不相同。如果你使用水平方向和垂直方向相同的像素数绘制一个方框，那么你会看到，该方框不是正方形而是个矩形，而使用PBU计量的相同单位数将绘出正方形。因此，在进行单位转换时，需要指明按那么方向进行转换。

示  例：These statements convert 35 horizontal pixels to PowerBuilder units and set the variable Value equal to the converted value:

integer Value

Value = PixelsToUnits(35, XPixelsToUnits!)

 

12、PopulateError()

功  能：以应用程序定制的错误号和错误信息填充Error对象，该函数不触发应用对象的SystemError事件。

语  法：PopulateError ( number, text )

参  数：number：integer类型，指定要保存到Error对象number属性中的值；

text：string类型，指定要保存到Error对象text属性中的值。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。

用  法：当应用程序需要根据变量的当前取值来定制Error对象时，可以使用PopulateError()函数来填充Error对象的number和text属性，同时该函数根据上下文自动填充Error对象的其它属性。

定制了Error对象后，应用程序可以使用不带参数的SignalError()函数触发应用对象的SystemError事件。这样，在SystemError事件的事件处理程序中可以编写处理定制错误和系统错误的通用代码。如果应用程序没有对SystemError事件编写事件处理程序，那么SignalError()函数什么也不做。

示  例：The gf_DoSomething function takes a table name and a record and returns 0 for success and a negative number for an error. The following statements set the number and text values in the Error object according to a script variable, then trigger a SystemError event once the processing is complete:

li_result = gf_DoSomething("Company", record_id)

IF (li_result < 0) THEN

CHOOSE CASE li_result

CASE -1

PopulateError(1, "No company record exists record id: " + record_id)

CASE -2

PopulateError(2, "That company record is &

currently locked. Please try again later.")

CASE -3

PopulateError(3, "The company record could not be updated.")

CASE else

PopulateError(999, "Update failed.")

END CHOOSE

SignalError()

END IF

 

13、RGB()

功  能：将代表红、绿、蓝三原色的三个整数组合成一个表示颜色的长整数。

语  法：RGB ( red, green, blue )

参  数：red：integer类型，指定颜色中的红色分量强度，有效值在0到255之间；

green：integer类型，指定颜色中的绿色分量强度，有效值在0到255之间；

blue：integer类型，指定颜色中的蓝色分量强度，有效值在0到255之间。

返回值：Long。函数执行成功时返回由指定分量确定的颜色，用长整数表示。发生错误时返回-1。如果任何参数的值为NULL，RGB()函数返回NULL。

用  法：RGB()函数使用下述公式计算表示颜色的长整数：65536 * Blue+ 256 * Green+ Red其中，Blue代表蓝色分量，Green代表绿色分量，Red代表红色分量。各分量中，数值越小，亮度越低，数值越大，亮度越高。例如，RGB ( 0, 0, 0 )为黑色（亮度最低），RGB ( 255, 255,255 )为白色（亮度最高）。

示  例：This statement returns a long that represents black:

RGB(0, 0, 0)

 

This statement returns a long that represents white:

RGB(255, 255, 255)

 

These statements set the color properties of the StaticText st_title to be green letters on a dark magenta background:

st_title.TextColor = RGB(0, 255, 0)

st_title.BackColor = RGB(128, 0, 128)

 

14、SetNull()

功  能：将指定变量的值设置为NULL。这里的变量可以是除数组、结构、自动实例化对象之外的任何数据类型。

语  法：SetNull ( anyvariable )

参  数：anyvariable：要将其值设置为NULL的变量。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。如果任何参数的值为NULL，SetNull()函数返回NULL。

用  法：PowerBuilder应用程序在说明变量时，并不自动地将其初值设置为NULL，而是根据类型的不同而设置不同的初值，比如，数值类型的变量自动初始化为0，字符串型变量自动初始化为空字符串（""）。因此，如果需要将某个变量的值设置为NULL，就需要使用SetNull()函数来完成任务了。一般来说，NULL值往往应用在数据库值未确定的列上。

示  例：This statement sets the variable Salary to NULL:

SetNull(Salary)

　

 

15、SetPointer()

功  能：设置鼠标指针。

语  法：SetPointer ( type )

参  数：type：Pointer枚举类型，指明要设置为哪种鼠标指针。

返回值：Pointer。返回更换前的鼠标指针，以便于应用程序恢复原有指针。如果参数type的值为NULL，SetPointer()函数返回NULL。

用  法：type参数的可能取值为：Arrow!、Cross!、Beam!、HourGlass!、SizeNS!、SizeNESW!、SizeWE!、

SizeNWSE!、UpArrow!。

示  例：This statement sets the pointer to the hourglass shape:

SetPointer(HourGlass!)

 

This example saves the old pointer and restores it when a long activity is completed:

pointer oldpointer // Declares a pointer variable

oldpointer = SetPointer(HourGlass!)

... // Performs some long activity

SetPointer(oldpointer)

 

16、SignalError()

功  能：以编程方式触发应用对象的SystemError事件。

语  法：SignalError ( { number }, { text } )

参  数：number：integer类型，可选项，指定出错编号，该编号将保存到Error对象的number属性中；

text：string类型，可选项，指定出错信息，该信息将保存到Error对象的text属性中。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。

用  法：SignalError()函数通常用于测试应用程序的出错处理代码，它以人工方式产生错误，以此模拟应用程序运行过程中可能出现的错误。我们知道，应用程序本身产生错误的条件往往不容易在测试时遇到。当应用程序使用PopulateError()函数定制了Error对象后，可以以不带参数的方式调用SignalError()函数，由该函数触发应用对象的SystemError事件。如果我们在调用SignalError()函数时指定了参数number和text，那么SignalError()函数将根据上下文填充Error对象的所有属性，然后触发应用对象的SystemError事件。如果应用程序没有对应用对象的SystemError事件编写事件处理程序，那么SignalError()函数什么也不做。

示  例：These statements set values in the Error object and then trigger a SystemError event so the error processing for these values can be tested:

int error_number

string error_text

Error.Number = 1010

Error.Text = "Salary must be a positive number."

Error.Windowmenu = "w_emp"

error_number = Error.Number

error_text = Error.Text

SignalError(error_number, error_text)

 

17、Sleep()

功  能：使应用程序暂停执行指定的时间，以秒为单位。

语  法：Sleep ( seconds )

参  数：seconds：Long类型，指定应用程序要暂停执行的时间，以秒为单位。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。

示  例：This example pauses the application for 5 seconds:

Sleep ( 5 )

 

18、UnitsToPixels()

功  能：将PowerBuilder单位（PBU）转换为像素。

语  法：UnitsToPixels ( units, type )

参  数：units：integer类型，指定要转换为像素的PowerBuilder单位（PBU）数；

type：ConvertType枚举类型，指定按哪个方向进行转换。有效取值为：

XUnitsToPixels! -- 按水平方向转换PBU；

YUnitsToPixels! -- 按垂直方向转换PBU。

返回值：Integer。函数执行成功时返回units参数指定PBU数按指定方向转换成的像素数，发生错误时返回-1。如果任何参数的值为NULL，UnitsToPixels()函数返回NULL。

用  法：窗口中水平方向和垂直方向相同的像素数表示的距离并不相同。如果你使用水平方向和垂直方向相同的像素数绘制一个方框，那么你会看到，该方框不是正方形而是个矩形，而使用PBU计量的相同单位数将绘出正方形。因此，在进行单位转换时，需要指明按那么方向进行转换。

示  例：These statements convert 350 vertical PowerBuilder units to vertical pixels and set value equal to the converted value:

integer Value

Value = UnitsToPixels(350, YUnitsToPixels!)