OpenUserObjectWithParm

Adds a user object to the specified window 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 particular user object

Syntax 1 For user objects of a known datatype

Open a user object, allowing the application to select the user object’s type at runtime

Syntax 2 For user objects of unknown datatype


Syntax 1 For user objects of a known datatype

Description

Opens a user object of a known datatype and stores a parameter in the system’s Message object.

Applies to

Window objects

Syntax

windowname.OpenUserObjectWithParm ( userobjectvar, parameter 
	{, 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. OpenUserObjectWithParm places a reference to the opened user object in userobjectvar.

parameter

The parameter you want to store in the Message object when the user object is opened. Parameter must have one of these datatypes:

  • String

  • Numeric

  • PowerObject

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.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, OpenUserObjectWithParm returns null.

Usage

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 would 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 opened user object, it is a good idea to access the value passed in the Message object immediately because some other script may use the Message object for another purpose.

NoteAvoiding 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.

Examples

Example 1

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")

Example 2

The user object’s Constructor event script has the following statement:

st_empname.Text = Message.StringParm

Example 3

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)

See also


Syntax 2 For user objects of unknown datatype

Description

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.

Applies to

Window objects

Syntax

windowname.OpenUserObjectWithParm ( userobjectvar, parameter, 
	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. OpenUserObjectWithParm places a reference to the opened user object in userobjectvar.

parameter

The parameter you want to store in the Message object when the user object is opened. Parameter must have one of these datatypes:

  • String

  • Numeric

  • PowerObject

userobjecttype

A string whose value is the datatype of the user object you want to open. 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.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, OpenUserObjectWithParm returns null.

Usage

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 would 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 opened user object, it is a good idea to access the value passed in the Message object immediately because some other script may use the Message object for another purpose.

NoteAvoiding 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 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.

Examples

Example 4

The following statement displays an instance of a user object u_data of type u_benefit_plan at location 20,100 in the window w_hresource. The parameter "Benefits" is stored in message.StringParm:

DragObject u_data

w_hresource.OpenUserObjectWithParm(u_data, &

		"Benefits", "u_benefit_plan", 20, 100)

Example 5

These statements open a user object of the type specified in the string s_u_name and store the reference to the user 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 user object is at the default coordinates 0,0 in the window 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)

Example 6

The following statements display a user object of the type specified in the string s_u_name and store the reference to the user object in the variable u_to_open. The parameter is numeric so it is stored in message.DoubleParm. The user object is at the coordinates 100,200 in the window 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)

See also