Closes a window and stores a return value in the Message object. You should use CloseWithReturn only for response windows.
Window objects
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:
|
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.
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. Before executing the event scripts, it also stores returnvalue in the Message object. Then PocketBuilder 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.
PocketBuilder 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.
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
