OpenTab

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

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.

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

OpenTabWithParm

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.

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

OpenTabWithParm