CloseWithReturn
PowerScript function
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
|
1 |
CloseWithReturn ( windowname, returnvalue ) |
|
Argument |
Description |
|---|---|
|
windowname |
The name of the window you want to |
|
returnvalue |
The value you want to store in the Message object
|
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:
|
1 |
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:
|
1 |
CloseWithReturn(Parent, sle_signon_id.Text) |
The script for the menu item is:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
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