PowerBuilder Manual Book Part 7

PowerBuilder Manual Book Part 7

PowerBuilder Curriculum Part 7

13. window

(1), Open

Function:
Open the window.
This function has two syntax forms:
Syntax 1. Open the window Object whose Data Type Is known during programming;
Syntax 2. Open the window Object whose Data Type can only be determined after the program runs.

Syntax:
Syntax 1, Open ( windowvar {, Parent } )
Syntax 2, Open ( windowvar, WindowType {, Parent } )

parameter:
Syntax 1,
windowvar: the Name Of the window To Open, you can use the window Object Name defined By the window brush, Or you can use a variable Of the window Object.
the Open() Function places a reference To the Open window In the windowvar variable
Parent: optional, specifies the Parent window Of the window To be opened, And the window To be opened becomes a child window Of the Parent window. This parameter needs To be specified only when the window To be opened needs To be a child window Of a certain window.
If the Application uses the Open() Function To Open a child window Or pop-up window And omits This parameter, Then the current active window becomes the Parent window Of the opened window
Syntax 2,
windowvar: specifies the window variable Name, And the Open() Function puts the reference Of the Open window Into the variable
WindowType: String Type, specify the Data Type Of the window To be opened, the window Data Type specified By This parameter must be the same as the windowvar parameter
the Type Of the Number Is the same Or the successor Object Of the windowvar Type
Parent: optional, specify the Parent window Of the window To be opened, the window To be opened becomes the child window Of the Parent window, only when the window To be opened needs To be a certain
This parameter needs To be specified only when a child window Of a window Is Selected.

Return Value:
Syntax 1,
Return Value: Integer. the Function returns 1 On success And -1 On Error. If the Value Of Any parameter Is Null, the Open() Function returns Null.
Syntax 2,
Return Value: Integer. the Function returns 1 On success And -1 On Error. If the Value Of Any parameter Is Null, the Open() Function returns Null.

(2), Close

Function:
Closes the window And frees the memory occupied By the window And controls On the window.

Syntax:
Close(windowname)

parameter:
windowname: the Name Of the window To Close

Return Value:
Return Value: Integer.
the Function returns 1 On success And -1 On Error.
If the Value Of the parameter windowname Is Null, the Close() Function returns Null.

usage
After the Application program uses Open() Or Other Open cluster functions To Open the window, when the window Is Not needed, it can use Close() To Close the window And release the memory occupied By the window And All controls On the window.
the execution process Of the Close () Function Is: If the CloseQuery And/Or Close Event Of the window To be closed has written Event handlers, Then Execute these Event handlers, Delete the window To be closed From the screen, Close the window, And Then Call Close () the statement following the Function statement.
when the window Is closed, the Application can no longer Access the properties, instance Variables, Object functions, And controls On the closed window.
If the Application still accesses the above features After closing the window, a runtime Error will be raised.
Of course, the Application can also prevent the window From being closed. the method Is very simple. Just use the Return statement To Return 1 In the CloseQuery Event handler that wants To prevent the window From being closed. the Format Is: RETURN1

(3), OpenWithParm

Function:
Open the window With parameters, similar To the Open() Function To Open the window, OpenWithParm() has two Syntax formats:
Syntax 1. Open window objects With known Data types when programming With parameters;
Syntax 2: Open the window Object whose Data Type can only be determined after the program runs With parameters.

Syntax:
Syntax 1,
OpenWithParm(windowvar,parameter{,Parent})
Syntax 2,
OpenWithParm(windowvar,parameter,WindowType{,Parent})

parameter:
Syntax 1,
windowvar: the Name Of the window To Open, you can use the window Object Name defined By the window brush, Or you can use a variable Of the window Object. the Open() Function places a reference To the Open window In the windowvar variable
parameter: Specify the Data To be passed To the Open window, the Data Is stored In the properties Of the Message Object, the Data Type Of the parameter parameter must be one Of the following three types: String, Numeric, PowerObject
Parent: optional, specifies the Parent window Of the window To be opened, And the window To be opened becomes a child window Of the Parent window. This parameter needs To be specified only when the window To be opened needs To be a child window Of a certain window. If the Application uses the Open() Function To Open a child window Or pop-up window And omits This parameter, Then the current active window becomes the Parent window Of the opened window
Syntax 2,
windowvar: specifies the window variable Name, And the Open() Function puts the reference Of the Open window Into the variable
parameter: Specify the Data To be passed To the Open window, the Data Is stored In the properties Of the Message Object, the Data Type Of the parameter parameter must be one Of the following three types: String, Numeric, PowerObject
WindowType: String Type, specifies the Data Type Of the window To be opened, the window Data Type specified By This parameter must be the same as the Type Of the windowvar parameter Or a successor Object Of the windowvar Type
Parent: optional, specifies the Parent window Of the window To be opened, And the window To be opened becomes a child window Of the Parent window. This parameter needs To be specified only when the window To be opened needs To be a child window Of a certain window. If the Application uses the Open() Function To Open a child window Or pop-up window And omits This parameter, Then the current active window becomes the Parent window Of the opened window

Return Value:
Syntax 1,
Return Value: Integer. the Function returns 1 On success And -1 On Error. If the Value Of Any parameter Is Null, the OpenWithParm() Function returns Null.
Syntax 2,
Return Value: Integer. the Function returns 1 On success And -1 On Error. If the Value Of Any parameter Is Null, the OpenWithParm() Function returns Null.

usage
the Message Object Message has three properties For storing the Data passed To the Open window By the OpenWithParm() Function. Depending On the Data Type Of the parameter parameter, the Value Of the parameter Is stored In different properties Of the Message Object.

(4), CloseWithReturn

Function:
Close the window And save the return value In the Message object, this function can only be used For the response window

Syntax:
CloseWithReturn( windowname, returnvalue)

parameter:
windowname: the name of the window to Close
returnvalue: Specifies the value saved In the Message object when the window is closed. The code segment that calls the CloseWithReturn() function obtains the value passed By the closed window when the window is closed By viewing the value of the Message object property.
The returnvalue parameter must be one of the following three types: String, Numeric, PowerObject

return value:
Return value: Integer.
The function returns 1 on success And -1 on error.
If any value of the parameter is Null, the CloseWithReturn() function returns Null.

(5), OpenSheet

Function:
Open an MDI child window In the MDI frame window, And Create a menu item that selects the child window In the specified menu

Syntax:
OpenSheet(sheetrefvar{,windowtype},mdiframe{,position{,arrangeopen}})

parameter:
sheetrefvar: Specifies the name of the window to Open as a worksheet
windowtype: string type, optional, specifies the type of window to Open (that is, the name of the window object saved In the window brush)
mdiframe: Specifies the name of the MDI frame window Where the worksheet will be placed
position: an optional parameter, specifying the name of the opened worksheet as a menu item to be displayed under which menu title. By default, it is placed under the penultimate menu title. The reason is that most commercial software The last two menu titles are Window And Help. It is a reasonable choice to put the name of the worksheet In the Window menu title For selecting the worksheet window.
arrangeopen: ArrangeOpen enumeration type, optional parameter, but if this parameter is selected, the position parameter must also be specified at the same time. The arrangeopen parameter tells the system how to display the Open worksheet

return value:
Return value: Integer.
The function returns 1 on success And -1 on error.
If any value of the parameter is Null, the OpenSheet() function returns Null.

usage
Possible Values For the arrangeopen parameter are: Cascaded!
Place one worksheet on top of the other, each offset a bit to the bottom right, so that the title bars of All worksheets are visible to the user. The value is
The default selection For the OpenSheet() function.
Layered! displays the worksheet In the upper left corner of the client area And maximizes the worksheet so that it fills the entire client area of the MDI frame window.
The Original! operation is the same as the Cascaded! parameter, except that the window is Not enlarged, but is displayed at the size when the window is defined.

(6), OpenSheetWithParm

Function:
Open the MDI child window In the MDI frame window, And save the parameters In the Message object For transmission.

Syntax:
OpenSheetWithParm(sheetrefvar,parameter{,windowtype},mdiframe{,position{,arrange Open}}

parameter:
sheetrefvar: Specifies the name of the window to Open as a worksheet
parameter: Specifies the data to be passed to the Open worksheet, which is stored In the properties of the Message object, And the data type of the parameter parameter must be one of the following three types: String, Numeric, PowerObject
windowtype: string type, optional, specifies the type of window to be opened (that is, the name of the window object saved In the window brush)
mdiframe: Specifies the name of the MDI frame window Where the worksheet will be placed
position: an optional parameter, specifying the name of the opened worksheet as a menu item to be displayed under which menu title. By default, it is placed under the penultimate menu title. The reason is that most commercial software The last two menu titles are Window And Help. It is a reasonable choice to put the name of the worksheet In the Window menu title For selecting the worksheet window.
arrangeopen: ArrangeOpen enumeration type, optional parameter, but if this parameter is selected, the position parameter must also be specified at the same time. The arrangeopen parameter tells the system how to display the Open worksheet

return value:
Return value: Integer. The function returns 1 on success And -1 on error. If any value of the parameter is Null, the OpenSheet() function returns Null.

usage
Possible Values For the arrangeopen parameter are: Cascaded!
Place one worksheet on top of the other, each offset a bit to the bottom right, so that the title bars of All worksheets are visible to the user. The value is
The default selection For the OpenSheet() function.
Layered! displays the worksheet In the upper left corner of the client area And maximizes the worksheet so that it fills the entire client area of the MDI frame window.
The Original! operation is the same as the Cascaded! parameter, except that the window is Not enlarged, but is displayed at the size when the window is defined.

14. Internationalization

(1), Reverse

Function:
Reverse the Order Of characters In a String

Syntax:
Reverse ( String )

parameter:
String: the String whose Character Order Is To be reversed

Return Value:
Return Value: String.
When the Function executes successfully, it returns a String With characters reversed, And If an Error occurs, it returns an empty String ("").

usage
the Reverse() Function places the Last Character In one String at the First Character Position Of another String, the second-to-last Character at the Second Character Position Of another String, And so On

(2), ToAnsi

Function:
Convert Unicode characters To ANSI characters.

Syntax:
ToAnsi ( String )

parameter:
String: the Unicode encoded String To be converted

Return Value:
Return Value: Blob.
When the Function executes successfully, it returns the ANSI-encoded Blob Type Data corresponding To the specified String, And returns a Null Value (Null) When an Error occurs.

(3), ToUnicode

Function:
Convert ANSI characters To Unicode characters.

Syntax:
ToUnicode( Blob)

parameter:
Blob: ANSI-encoded Blob Type Data To be converted

Return Value:
Return Value: String.
When the Function executes successfully, it returns the Unicode-encoded String corresponding To the specified String, And returns an empty String When an Error occurs.

15. Others

(1), IntHigh

Function:
Get the high word Of a Long Value

Syntax:
IntHigh ( Long )

parameter:
Long: Long Type Value Or variable

Return Value:
Return Value: Integer.
When the Function executes successfully, it returns the high word Of the parameter Long, And When an Error occurs, it returns -1.
If the Value Of the parameter Long Is Null, the IntHigh() Function returns Null.

usage
the IntHigh() Function Is usually used To decompose Return Values And Windows messages Of External C Or C++ language functions.

(2), IntLow

Function:
Get the low word Of a Long Value

Syntax:
IntLow ( Long )

parameter:
Long: Long Type Value Or variable

Return Value:
Return Value: Integer.
When the Function executes successfully, it returns the low-order word Of the parameter Long, And When an Error occurs, it returns -1.
If the Value Of the parameter Long Is Null, the IntLow() Function returns Null.

usage
the IntLow() Function Is typically used To decompose Return Values And Windows messages From External C Or C++ language functions. See the IntHigh() Function For an example.

(3), IsValid

Function:
Checks whether the Object variable has been instantiated, that Is, whether the Value Of the instance variable Is a valid Object Handle.

Syntax:
IsValid ( objectname )

parameter:
objectname: the Name Of the Object To be detected

Return Value:
Return Value: Boolean.
If the specified Object has created an Object instance, Then the IsValid () Function returns True, otherwise returns False.
If the Value Of the parameter objectname Is Null, the IsValid() Function returns Null.

(4), KeyDown

Function:
Checks If the user pressed the specified Key On the keyboard

Syntax:
KeyDown (keycode)

parameter:
keycode: keycode Enumeration Type Or Integer Type, indicating the Key To be detected Or the ASCII Value Of a Key

Return Value:
Return Value: Boolean.
If the user presses the Key specified By the keycode parameter, the Function returns True, otherwise it returns False.
If the Value Of the parameter keycode Is Null, the KeyDown() Function returns Null.

usage
the KeyDown() Function Is usually called In the Event handler Of an Event. it does Not indicate which Character the user has typed, but that the user Is pressing the Key when the current Event (that Is, the Event that calls the KeyDown() Function In the Event handler) occurs. press which button.
Generally speaking, the Application calls the KeyDown() Function In the Key Event Of the window Or the Key Event Of the Control To detect whether the user presses a special Key.
For controls, PowerBuilder does Not define a predefined Key Event, it does Not matter
If you want the Application To detect the user's keys after the control gets the focus, you only need to define a user event for the control, and map pbm_keydown (other controls) or pbm_dwnkey (data window control) to the user event.

(5), MessageBox

Function:
Show a Message dialog

Syntax:
MessageBox(Title,Text{,Icon{,button{,Default}}})

parameter:
Title: String Type, specifies the Title Of the Message dialog box
Text: Specify the Message displayed In the Message dialog box, This parameter can be a numeric Data Type, String Or Boolean Value
Icon: Icon Enumeration Type, optional, Specify the Icon To be displayed On the Left side Of the dialog box
button: button Enumeration Type, optional, specifies the button displayed at the bottom Of the dialog box
Default: numeric Type, optional, Specify the button Number as the Default button, the button Number Is counted From Left To Right, the Default Value Is 1, If the Number specified By This parameter exceeds the Number Of displayed buttons, Then MessageBox() the Function will use the Default Value

Return Value:
Return Value: Integer.
When the Function executes successfully, it returns the button Number Selected By the user (such as 1, 2, 3, etc.), And returns -1 When an Error occurs.
If the Value Of Any parameter Is Null, the MessageBox() Function returns Null.

usage
When your Application needs To display a short Message (such as displaying errors, warnings, etc.), there Is no need To Create windows And Arrange controls From scratch. Using the MessageBox() Function Is simple And convenient.
Only after the user responds To the window can the program Continue To Run.
the Icon parameter Of the MessageBox() Function specifies the Icon displayed In the window, it Is an Enumeration Type, And the possible Values are:
Icon Information! StopSign! Exclamation! Question! None!
no Icon Where Information! Is the Default Value For the Icon parameter.
the button parameter specifies which buttons are displayed In the window, And the valid Values are:
OK! "OK" button
OKCancel! "OK", "Cancel" button
YesNo! "Yes", "No" buttons
YesNoCancel! "Yes", "No", "Cancel" buttons
RetryCancel! "Retry", "Cancel" button
AbortRetryIgnore! "Abort", "Retry", "Ignore" buttons

(6), PixelsToUnits

Function:
Convert Pixel Values To PowerBuilder Units PBU

Syntax:
PixelsToUnits ( pixels, Type )

parameter:
pixels: Integer Type, specifies the Number Of pixels To be converted To PowerBuilder Units
Type: ConvertType Enumeration Type, specifying which direction To Convert. Valid Values are:
XPixelsToUnits! - Convert pixels horizontally;
YPixelsToUnits! - Convert pixels vertically

Return Value:
Return Value: Integer.
When the Function executes successfully, it returns the Number Of PowerBuilder Units converted From the Number Of pixels specified By the pixels parameter In the specified direction, And returns -1 When an Error occurs.
If the Value Of Any parameter Is Null, the PixelsToUnits() Function returns Null.

usage
the same Number Of pixels In the horizontal direction And the vertical direction In the window represent different distances.
If you Draw a box With the same Number Of pixels horizontally And vertically, you will see that the box Is Not a square but a rectangle, While the same Number Of Units measured In PBU will Draw a square.
Therefore, When performing unit conversion, it Is necessary To indicate the direction In which To Convert.

(7), PopulateError

Function:
Fill the Error Object With the Error Number And Error information customized By the Application. This Function does Not Trigger the SystemError Event Of the Application Object.

Syntax:
PopulateError (Number, Text)

parameter:
Number: Integer Type, specifying the Value To be saved In the Number property Of the Error Object
Text: String Type, specify the Value To be saved In the Text property Of the Error Object

Return Value:
Return Value: Integer.
the Function returns 1 On success And -1 On Error.

usage
When the Application needs To customize the Error Object according To the current Value Of the variable, the PopulateError() Function can be used To Fill the Number And Text properties Of the Error Object, And This Function will automatically Fill In Other properties Of the Error Object according To the context.
After customizing the Error Object, the Application can use the SignalError() Function without parameters To Trigger the SystemError Event Of the Application Object.
In This way, common code For handling custom errors And System errors can be written In the Event handler Of the SystemError Event.
If the Application does Not Write an Event handler For the SystemError Event, the SignalError() Function does nothing.

(8), RGB

Function:
Combine three integers representing the primary colors red, green, And blue Into one Long Integer representing the Color

Syntax:
RGB ( red, green, blue )

parameter:
red: Integer Type, specifies the intensity Of the red component In the Color, And the valid Value Is Between 0 And 255
green: Integer Type, specifies the intensity Of the green component In the Color, And the valid Value Is Between 0 And 255
blue: Integer Type, specifies the intensity Of the blue component In the Color, And the valid Value Is Between 0 And 255

Return Value:
Return Value: Long.
When the Function executes successfully, it returns the Color determined By the specified component, represented By a Long Integer.
returns -1 On Error. If the Value Of Any parameter Is Null, the RGB() Function returns Null.

usage
the RGB() Function uses the following formula To calculate the Long Integer representing the Color: 65536 * blue+ 256 * green+ red
Among them, blue represents the blue component, green represents the green component, And red represents the red component.
In each component, the smaller the Value, the Lower the brightness, And the larger the Value, the higher the brightness.
For example, RGB ( 0, 0, 0 ) Is black (lowest brightness), And RGB ( 255, 255,255 ) Is white (brightest).

(9), SetNull

Function:
Sets the Value Of the specified variable To Null. Variables here can be Of Any Data Type except arrays, structures, And auto-instantiated objects.

Syntax:
SetNull(anyvariable)

parameter:
anyvariable: the variable whose Value Is To be Set To Null

Return Value:
Return Value: Integer.
the Function returns 1 On success And -1 On Error.
If the Value Of Any parameter Is Null, the SetNull() Function returns Null.

usage
When the PowerBuilder Application program declares Variables, it does Not automatically Set its initial Value To Null, but Sets different initial Values according To different types. For example, Variables Of numeric Type are automatically initialized To 0, And Variables Of String Type are automatically initialized. Is an empty String ("").
Therefore, If you need To Set the Value Of a variable To Null, you need To use the SetNull() Function To complete the task.
Generally speaking, Null Values are often applied To Columns whose Database Values are Not determined.

(10), SetPointer

Function:
Set the mouse Pointer.

Syntax:
SetPointer ( Type )

parameter:
Type: Pointer Enumeration Type, indicating which mouse Pointer To Set

Return Value:
Return Value: Pointer.
Returns the mouse Pointer before the replacement, so that the Application can restore the original Pointer.
If the Value Of the parameter Type Is Null, the SetPointer() Function Returns Null.
the possible Values Of the usage Type parameter are: Arrow!, Cross!, Beam!, HourGlass!, SizeNS!, SizeNESW!, SizeWE!, SizeNWSE!, UpArrow!.

(11), SignalError

Function:
Programmatically Trigger the SystemError Event Of the Application Object.

Syntax:
SignalError ( { Number }, { Text } )

parameter:
Number: Integer Type, optional, specifies the Error Number, which will be saved In the Number property Of the Error Object
Text: String Type, optional, specifies the Error Message, which will be saved In the Text property Of the Error Object

Return Value:
Return Value: Integer. the Function returns 1 On success And -1 On Error.

usage
the SignalError() Function Is usually used To test the Error handling code Of the Application. It artificially generates errors To simulate errors that may occur during the Running Of the Application.
We know that the conditions that generate errors In the Application itself are often Not easy To encounter during testing.
After the Application customizes the Error Object Using the PopulateError() Function, the SignalError() Function can be called without parameters, And the Function triggers the SystemError Event Of the Application Object.
If We specify the parameters Number And Text when calling the SignalError() Function, the SignalError() Function will Fill In All properties Of the Error Object according To the context, And Then Trigger the SystemError Event Of the Application Object.
If the Application does Not Write an Event handler For the Application Object's SystemError event, the SignalError() function does nothing.

(12), UnitsToPixels

Function:
Convert PowerBuilder Units (PBU) To Pixels

Syntax:
UnitsToPixels ( Units, Type )

parameter:
Units: Integer Type, specifying the Number Of PowerBuilder units (PBU) To be converted To Pixels
Type: ConvertType Enumeration Type, specifying which direction To Convert. Valid Values are: XUnitsToPixels! - translate the PBU horizontally;
YUnitsToPixels! - translate the PBU vertically

Return Value:
Return Value: Integer.
When the Function executes successfully, it returns the Number Of Pixels converted From the Number Of PBUs specified By the Units parameter In the specified direction, And returns -1 When an Error occurs. If the Value Of Any parameter Is Null, the UnitsToPixels() Function returns Null.

usage
the same Number Of Pixels In the horizontal direction And the vertical direction In the window represent different distances.
If you Draw a box With the same Number Of Pixels horizontally And vertically, you will see that the box Is Not a square but a rectangle, While the same Number Of Units measured In PBU will Draw a square.
Therefore, When performing unit conversion, it Is necessary To indicate the direction In which To Convert.

PowerBuilder Manual Book Part 8 ClickHere

Good Luck!