Adds a user object to a window or visual user object and makes all its properties and controls available to scripts, as OpenUserObject does. OpenUserObjectWithParm also stores a parameter in the system’s Message object so that it is accessible to the opened object.
To |
Use |
|---|---|
Open an instance of a specified visual user object |
|
Open a visual user object, allowing the application to select the user object’s type at runtime |
Opens a user object of a known datatype and stores a parameter in the system’s Message object.
Window objects and visual user objects
objectname.OpenUserObjectWithParm ( targetobjectvar, parameter
{, x, y } )
Argument |
Description |
|---|---|
objectname |
The name of the window or user object in which to open the target user object. |
targetobjectvar |
The name of the target object you want to display. You can specify a user object defined in the User Object painter (which is a user object datatype) or a variable of the desired user object datatype. OpenUserObject places a reference to the opened target object in targetobjectvar. |
parameter |
The parameter you want to store in the Message object when the target object is opened. Parameter must have one of these datatypes:
|
x (optional) |
The x coordinate in PowerBuilder units of the target object within the objectname object. The default is 0. |
y (optional) |
The y coordinate in PowerBuilder units of the target object within the objectname object. The default is 0. |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, OpenUserObjectWithParm returns null.
The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenUserObjectWithParm, scripts for the opened user object check one of the following properties:
Message object property |
Argument datatype |
|---|---|
message.DoubleParm |
Numeric |
message.PowerObjectParm |
PowerObject (PowerBuilder objects, including user-defined structures) |
message.StringParm |
String |
In the target user object, consider accessing the value passed in the Message object immediately, because some other script may use the Message object for another purpose.
Avoiding null object references
When you pass a PowerObject as a parameter, you are passing
a reference to the object. The object must exist when you refer
to it later or you get a null object reference, which causes an
error. For example, if you pass the name of a control on a window
that is being closed, that control will not exist when a script
accesses the parameter.
See also the usage notes for OpenUserObject, all of which apply to OpenUserObjectWithParm.
This statement displays an instance of a user object
named u_Employee in the window w_emp and
stores the string James Newton in
Message.StringParm. The Constructor event script for the user object
uses the string parameter as the text of a StaticText control st_empname in
the object. The script that opens the user object has the following
statement:
w_emp.OpenUserObjectWithParm(u_Employee, "Jim Newton")
The target user object’s Constructor event script has the following statement:
st_empname.Text = Message.StringParm
The following statements display an instance of a user object u_to_open in the window w_emp and store a number in message.DoubleParm:
u_employee u_to_open
integer age = 50
w_emp.OpenUserObjectWithParm(u_to_open, age)
Opens a user object when the datatype of the user object is not known until the script is executed. In addition, OpenUserObjectWithParm stores a parameter in the system’s Message object so that it is accessible to the opened object.
Window objects and user objects
objectname.OpenUserObjectWithParm ( targetobjectvar, parameter,
targetobjecttype {, x, y } )
Argument |
Description |
|---|---|
objectname |
The name of the window or user object in which to open the target user object. |
targetobjectvar |
A variable of datatype DragObject. OpenUserObjectWithParm places a reference to the opened target object in targetobjectvar. |
parameter |
The parameter you want to store in the Message object when the target object is opened. Parameter must have one of these datatypes:
|
targetobjecttype |
A string whose value is the datatype of the target object to open. The datatype of targetobjecttype must be a descendant of targetobjectvar. |
x (optional) |
The x coordinate in PowerBuilder units of the user object within the objectname object’s frame. The default is 0. |
y (optional) |
The y coordinate in PowerBuilder units of the target object within the objectname object’s frame. The default is 0. |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, OpenUserObjectWithParm returns null.
The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenUserObjectWithParm, scripts for the opened user object check one of the following properties.
Message object property |
Argument datatype |
|---|---|
message.DoubleParm |
Numeric |
message.PowerObjectParm |
PowerObject (PowerBuilder objects, including user-defined structures) |
message.StringParm |
String |
In the target user object, consider accessing the value passed in the Message object immediately, because some other script may use the Message object for another purpose.
Avoiding null object references
When you pass a PowerObject as a parameter, you are passing
a reference to the object. The object must exist when you refer
to it later or you will get a null object reference, which causes
an error. For example, if you pass the name of a control on an object
that is being closed, that control will not exist when a script
accesses the parameter.
See also the usage notes for OpenUserObject, all of which apply to OpenUserObjectWithParm.
The following statement displays an instance of a user object u_data of type u_benefit_plan at location 20,100 in the container object w_hresource. The parameter "Benefits" is stored in message.StringParm:
DragObject u_data
w_hresource.OpenUserObjectWithParm(u_data, &
"Benefits", "u_benefit_plan", 20, 100)
These statements open a user object of the type specified in the string s_u_name and store the reference to the object in the variable u_to_open. The script gets the value of s_u_name, the type of user object to open, from the database. The parameter is the text of the SingleLineEdit sle_loc, so it is stored in Message.StringParm. The target object is at the default coordinates 0,0 in the objectname object w_info:
DragObject u_to_open
string s_u_name, e_location
e_location = sle_location.Text
SELECT next_userobj INTO : s_u_name
FROM routing_table
WHERE ... ;
w_info.OpenUserObjectWithParm(u_to_open, &
e_location, s_u_name)
The following statements display a user object of the type specified in the string s_u_name and store the reference to the object in the variable u_to_open. The parameter is numeric, so it is stored in message.DoubleParm. The target object is at the coordinates 100,200 in the objectname object w_emp:
userobject u_to_open
integer age = 60
string s_u_name
s_u_name = sle_user.Text
w_emp.OpenUserObjectWithParm(u_to_open, age, &
s_u_name, 100, 200)
