Description
Closes a window and stores a return value in the Message object. You should use CloseWithReturn only for response windows.
Applies to
Window objects
Syntax
CloseWithReturn ( windowname, returnvalue )
|
Argument |
Description |
|---|---|
|
windowname |
The name of the window you want to close. |
|
returnvalue |
The value you want to store in the Message object when the window is closed. Returnvalue must be one of these datatypes:
|
Return value
Integer.
Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, CloseWithReturn returns null. The return value is usually not used.
Usage
The purpose of CloseWithReturn is to close a response window and return information from the response window to the window that opened it. Use CloseWithReturn to close a window, release the storage occupied by the window and all the controls in the window, and return a value.
Just as with Close, CloseWithReturn removes a window from view, closes it, and executes the script for the CloseQuery and Close events, if any. Do not call Close or CloseWithReturn from these events, since this produces an endless loop.
Before executing the event scripts, CloseWithReturn stores returnvalue in the Message object, and PowerBuilder executes the rest of the script that called the CloseWithReturn function.
After a window is closed, its properties, instance variables, and controls can no longer be referenced in scripts. If a statement in the script references the closed window or its properties or instance variables, an execution error results.
PowerBuilder stores returnvalue in the Message object properties according to its datatype. In the script that called CloseWithReturn, you can access the returned value by specifying the property of the Message object that corresponds to the return value's datatype.
|
Return value datatype |
Message object property |
|---|---|
|
Numeric |
Message.DoubleParm |
|
PowerObject (such as a structure) |
Message.PowerObjectParm |
|
String |
Message.StringParm |
Returning several values as a structure
To return several values, create a user-defined structure to hold the values and access the PowerObjectParm property of the Message object in the script that opened the response window. The structure is passed by value so you can access the information even if the original variable has been destroyed.
Referencing controls
User objects and controls are passed by reference, not by value. You cannot use CloseWithReturn to return a reference to a control on the closed window (because the control no longer exists after the window is closed). Instead, return the value of one or more properties of that control.
Preventing a window from closing
You can prevent a window from being closed with a return code of 1 in the script for the CloseQuery event. Use a RETURN statement.
Examples
This statement closes the response window w_employee_response, returning the string emp_name to the window that opened it:
CloseWithReturn(Parent, "emp_name")
Suppose that a menu item opens one window if the user is a novice and another window if the user is experienced. The menu item displays a response window called w_signon to prompt for the user's experience level. The user types an experience level in the SingleLineEdit control sle_signon_id. The OK button in the response window passes the text in sle_signon_id back to the menu item script. The menu item script checks the StringParm property of the Message object and opens the desired window.
The script for the Clicked event of the OK button in the w_signon response window is a single line:
CloseWithReturn(Parent, sle_signon_id.Text)
The script for the menu item is:
string ls_userlevel // Open the response window Open(w_signon) // Check text returned in Message object ls_userlevel = Message.StringParm IF ls_userlevel = "Novice" THEN Open(win_novice) ELSE Open(win_advanced) END IF
See also
