Adds a user object to the specified window and makes all its properties and controls available to scripts.
To |
Use |
|---|---|
Open an instance of a particular user object |
|
Open a user object, allowing the application to select the user object’s type during execution |
Opens a user object of a known datatype.
Window objects
windowname.OpenUserObject ( userobjectvar {, x, y } )
Argument |
Description |
|---|---|
windowname |
The name of the window in which you want to open the user object. |
userobjectvar |
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 userobjectvar. |
x (optional) |
The x coordinate in PowerBuilder units of the user object within the window’s frame. The default is 0. |
y (optional) |
The y coordinate in PowerBuilder units of the user object within the window’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, OpenUserObject returns null.
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 the properties of the user object. If you access the user object’s properties before you open it, an execution error will occur.
A user object that is part of a window’s definition (that is, it was added to the window in the Window painter) does not have to opened in a script. PocketBuilder opens it when it opens the window.
OpenUserObject adds the newly opened user object to the window’s Control array, which is a property that lists the window’s controls.
When you open a user object during execution, the window does not destroy the user object automatically when you close the window. You need to call CloseUserObject to destroy the user object, usually when the window closes. If you do not destroy the user object, it holds on to its allocated memory, resulting in a memory leak.
PocketBuilder 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).
Calling OpenUserObject twice
If you call Syntax 1 twice to open the same user object, PocketBuilder
activates the user object twice; it does not open two instances
of the user object.
This statement displays an instance of a user object named u_Employee in the upper left corner of the 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)
Opens a user object when the datatype of the user object is not known until the script is executed.
Window objects
windowname.OpenUserObject ( userobjectvar, userobjecttype {, x, y } )
Argument |
Description |
|---|---|
windowname |
The name of the window in which you want to open the user object. |
userobjectvar |
A variable of datatype DragObject. OpenUserObject places a reference to the opened user object in userobjectvar. |
userobjecttype |
A string whose value is the name of the user object you want to display. The datatype of userobjecttype must be a descendant of userobjectvar. |
x (optional) |
The x coordinate in PowerBuilder units of the user object within the window’s frame. The default is 0. |
y (optional) |
The y coordinate in PowerBuilder units of the user object within the window’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, OpenUserObject returns null.
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 the properties of the user object. If you access the user object’s properties before you open it, an execution error will occur.
A user object that is part of a window’s definition (that is, it was added to the window in the Window painter) does not have to be opened in a script. PocketBuilder opens it when it opens the window.
OpenUserObject adds the newly opened user object to the window’s Control array, which is a property that lists the window’s controls.
When you open a user object during execution, the window does not destroy the user object automatically when you close the window. You need to call CloseUserObject to destroy the user object, usually when the window closes. If you do not destroy the user object, it holds on to its allocated memory, resulting in a memory leak.
PocketBuilder 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, PocketBuilder 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 descendent 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 PKD file (PocketBuilder dynamic library) that you deliver with your application.
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)
