Adds a user object to a window or visual user object and makes all its properties and controls available to scripts.
Description
Opens a user object of a known datatype.
Applies to
Window objects and visual user objects
Syntax
objectname.OpenUserObject ( targetobjectvar {, 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 user 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 user object in targetobjectvar. |
|
x (optional) |
The x coordinate in PowerBuilder units of the target object within the first object's frame. The default is 0. |
|
y (optional) |
The y coordinate in PowerBuilder units of the target object within the first object's frame. The default is 0. |
Return value
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenUserObject returns null.
Usage
Use Syntax 1 when you know what user object you want to open. Use Syntax 2 when the application will determine what type of user object to open when the script runs.
You must open a user object before you can access its properties. If you access the user object's properties before you open it, an execution error occurs.
A user object that is part of a window definition (for example, if you added it in the Window painter), you do not need to open it using a script: PowerBuilder opens the object when it opens the window.
At runtime, OpenUserObject adds the newly opened user object to the first object's Control array.
Target objects are not automatically closed at runtime when you open and then close objectname. You need to explicitly call CloseUserObject to destroy a target user object, usually when the objectname object closes. If you do not destroy the target object, it holds on to its allocated memory, resulting in a memory leak.
PowerBuilder displays the user object when it next updates the display or at the end of the script, whichever comes first. For example, if you open several user objects in a script, they all display at once when the script is complete, unless some other statements cause a change in the screen's appearance (for example, the MessageBox function displays a message or the script changes a visual property of a control).
Calling OpenUserObject twice
If you call Syntax 1 twice to open the same user object, PowerBuilder activates the user object twice; it does not open two instances of the user object.
Examples
This statement displays an instance of a user object named u_Employee in the upper left corner of window w_emp (coordinates 0,0):
w_emp.OpenUserObject(u_Employee)
The following statements display an instance of a user object u_to_open at 200,100 in the window w_empstatus:
u_employee u_to_open w_empstatus.OpenUserObject(u_to_open, 200, 100)
The following statement displays an instance of a user object u_data at location 20,100 in w_info:
w_info.OpenUserObject(u_data, 20, 100)
See also
Description
Opens a user object when the datatype of the user object is not known until the script is executed.
Applies to
Window objects and visual user objects
Syntax
objectname.OpenUserObject ( targetobjectvar, 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. OpenUserObject places a reference to the opened user object in targetobjectvar. |
|
targetobjecttype |
A string whose value is the name of the user object you want to display. The datatype of targetobjecttype must be a descendant of targetobjectvar. |
|
x (optional) |
The x coordinate in PowerBuilder units of the user object within the first object's frame. The default is 0. |
|
y (optional) |
The y coordinate in PowerBuilder units of the user object within the first object's frame. The default is 0. |
Return value
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenUserObject returns null.
Usage
Use Syntax 1 when you know what user object you want to open. Use Syntax 2 when the application will determine what type of user object to open when the script runs.
You must open a user object before you can access its properties. If you access the user object's properties before you open it, an execution error occurs.
A user object that is part of a window definition (for example, if you added it in the Window painter), you do not need to open it using a script: PowerBuilder opens the object when it opens the window.
At runtime, OpenUserObject adds the newly opened user object to the first object's Control array.
Target objects are not automatically closed at runtime when you open and then close objectname. You need to explicitly call CloseUserObject to destroy a target user object, usually when the objectname object closes. If you do not destroy the target object, it holds on to its allocated memory, resulting in a memory leak.
PowerBuilder displays the user object when it next updates the display or at the end of the script, whichever comes first. For example, if you open several user objects in a script, they will all display at once when the script is complete, unless some other statements cause a change in the screen's appearance (for example, the MessageBox function displays a message or the script changes a visual property of a control).
The userobjecttype argument
When you use Syntax 2, PowerBuilder opens an instance of a user object of the datatype specified in userobjecttype and places a reference to this instance in the variable userobjectvar. To refer to the instance in scripts, use userobjectvar.
If userobjecttype is a descendant user object, you can only refer to properties, events, functions, or structures that are part of the definition of userobjectvar. For example, if a user event is declared for userobjecttype, you cannot reference it.
The object specified in userobjecttype is not automatically included in your executable application. To include it, you must save it in a PBD file (PowerBuilder dynamic library) that you deliver with your application.
Examples
The following example displays a user object of the type specified in the string s_u_name and stores the reference to the user object in the variable u_to_open. The user object is located at 100,200 in the window w_info:
DragObject u_to_open string s_u_name s_u_name = sle_user.Text w_info.OpenUserObject(u_to_open, s_u_name, 100, 200)
See also
