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.
To open |
Use |
|---|---|
A user object as a tab page |
|
A user object as a tab page, allowing the application to select the user object’s type at runtime |
Opens a custom visual user object of a known datatype as a tab page in a Tab control.
Tab controls
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. |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, OpenTab 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.
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.
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)
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.
Tab controls
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 |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, OpenTab 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.
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 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 PBD file (PowerBuilder dynamic library) that you deliver with you application.
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)
