OpenTabWithParm

Adds a visual user object to the specified window and makes all its properties and controls available to scripts, as OpenTab does. OpenTabWithParm also stores a parameter in the system's Message object so that it is accessible to the opened object.

To open

Use

A user object as a tab page

Syntax 1

A user object as a tab page, allowing the application to select the user object's type at runtime

Syntax 2


Syntax 1: For user objects of a known datatype

Description

Opens a custom visual user object of a known datatype as a tab page in a Tab control and stores a parameter in the system's Message object.

Applies to

Tab controls

Syntax

tabcontrolname.OpenTabWithParm ( userobjectvar, parameter, index )

Argument

Description

tabcontrolname

The name of the Tab control in which you want to open the user object as a tab page.

userobjectvar

The name of the custom visual user object you want to open as a tab page. You can specify a custom visual user object defined in the User Object painter (which is a user object datatype) or a variable of the desired user object datatype. OpenTabWithParm places a reference to the opened custom visual 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

index

The number of the tab before which you want to insert the new tab. If index is 0 or greater than the number of tabs, the tab page is inserted at the end.


Return value

Integer.

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

Usage

The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenTabWithParm, 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.

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 OpenTab, all of which apply to OpenTabWithParm.

Examples

This statement opens an instance of a user object named u_Employee as a tab page in the Tab control tab_empsettings. It also 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 tab page has the following statement:

tab_empsettings.OpenTabWithParm(u_Employee, &
      "James Newton", 0)

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

st_empname.Text = Message.StringParm

The following statements open an instance of a user object u_to_open as the first tab page in the Tab control tab_empsettings and store a number in message.DoubleParm. The last statement selects the tab page:

u_employee u_to_open
integer age = 50
tab_1.OpenTabWithParm(u_to_open, age, 1)
tab_1.SelectTab(u_to_open)

See also

OpenTab

Syntax 2: For user objects of unknown datatype

Description

Opens a visual user object as a tab page within a Tab control when the datatype of the user object is not known until the script is executed. In addition, OpenTabWithParm stores a parameter in the system's Message object so that it is accessible to the opened object.

Applies to

Tab controls

Syntax

tabcontrolname.OpenTabWithParm ( userobjectvar, parameter, userobjecttype, index )

Argument

Description

tabcontrolname

The name of the Tab control in which you want to open the user object as a tab page.

userobjectvar

A variable of datatype UserObject. OpenTabWithParm 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.

index

The number of the tab before which you want to insert the new tab. If index is 0 or greater than the number of tabs, the tab page is inserted at the end.


Return value

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

Usage

The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenTabWithParm, 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.

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 a window that is being closed, that control will not exist when a script accesses the parameter.

See also the usage notes for OpenTab, all of which apply to OpenTabWithParm.

Examples

The following statement opens an instance of a user object u_data of type u_benefit_plan as the last tab page in the Tab control tab_1. The parameter "Benefits" is stored in message.StringParm:

UserObject u_data
tab_1.OpenTabWithParm(u_data, &
      "Benefits", "u_benefit_plan", 0)

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 becomes the third tab page in the Tab control tab_1:

UserObject 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 ...  ;
 
tab_1.OpenTabWithParm(u_to_open, &
      e_location, s_u_name, 3)

The following 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 parameter is numeric so it is stored in message.DoubleParm. The user object becomes the first tab page in the Tab control tab_1:

UserObject u_to_open
integer age = 60
string s_u_name
 
s_u_name = sle_user.Text
tab_1.OpenTabWithParm(u_to_open, age, &
      s_u_name, 1)

See also

OpenTab