Opens a visual user object and makes it a tab page in the specified Tab control and makes all its properties and controls available to scripts.
Description
Opens a custom visual user object of a known datatype as a tab page in a Tab control.
Applies to
Tab controls
Syntax
tabcontrolname.OpenTab ( userobjectvar, 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. OpenTab places a reference to the opened custom visual user object in 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, OpenTab 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.
The tab page for the user object does not become selected. Scripts for constructor events of the controls on the user object do not run until the tab page is selected.
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 Tab control's definition (that is, it was added to the Tab control in the Window painter) does not have to be opened in a script. PowerBuilder opens it when it opens the window containing the Tab control.
OpenTab adds the newly opened user object to the Tab control's Control array, which is a property that lists the tab pages within the Tab control.
Opening the same object twice
If you call Syntax 1 twice to open the same user object, PowerBuilder does open the user object again as another tab page, in contrast to the behavior of Open and OpenUserObject.
Behavior change
In previous releases, calling the OpenTab function to open a user object as a tab page displayed the tab page even if the user object's Visible property was set to false. In current releases, the user object's Visible property must be set to true for the tab page to display.
Examples
This statement opens an instance of a user object named u_Employee as a tab page in the Tab control tab_1:
tab_1.OpenTab(u_Employee, 0)
The following statements open an instance of a user object u_to_open as a tab page in the Tab control tab_1. It becomes the first tab in the control:
u_employee u_to_open tab_1.OpenTab(u_to_open, 1)
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.
Applies to
Tab controls
Syntax
tabcontrolname.OpenTab ( userobjectvar, 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. OpenTab 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 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, OpenTab 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.
The tab page for the user object does not become selected. Scripts for Constructor events of the controls on the user object do not run until the tab page is selected.
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 Tab control's definition (that is, it was added to the Tab control in the Window painter) does not have to be opened in a script. PowerBuilder opens it when it opens the window containing the Tab control.
OpenTab adds the newly opened user object to the Tab control's Control array, which is a property that lists the tab pages within the Tab control.
Behavior change
In previous releases, calling the OpenTab function to open a user object as a tab page displayed the tab page even if the user object's Visible property was set to false. In current releases, the user object's Visible property must be set to true for the tab page to display.
Considerations when specifying a user object type
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 opens a user object as the last tab page in the Tab control tab_1. The user object is of the type specified in the string s_u_name and stores the reference to the user object in the variable u_to_open:
UserObject u_to_open string s_u_name s_u_name = sle_user.Text tab_1.OpenTab(u_to_open, s_u_name, 0)
See also
