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