OpenSheetWithParmInTabGroup

Description

Opens a sheet in a tab group within an MDI frame window for dockable windows. OpenSheetWithParmInTabGroup also stores a parameter in the system's Message object so that it is accessible to the opened sheet.

Applies to

Window objects

Syntax

OpenSheetWithParmInTabGroup ( sheetrefvar, parameter {, windowtype }, siblingname, sheetname )

Argument

Description

sheetrefvar

The name of any window variable that is not an MDI frame window. OpenSheetInwithParmTabGroup places a reference to the open sheet in sheetrefvar.

parameter

The parameter you want to store in the Message object when the sheet is opened. Parameter must have one of these datatypes:

  • String

  • Double

  • PowerObject

windowtype (optional)

A string whose value is the datatype of the window you want to open. The datatype of windowtype must be the same or a descendant of sheetrefvar.

siblingname

The name of a sibling window in either a docked state or in a non-document tab group. The sheet opens in that tab group.

sheetname

A unique string identifier for the sheet, which is used when layout is persisted.


Return value

Integer.

Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenSheetWithParmInTabGroup returns null. In some cases, such as if the windowtype argument is invalid, OpenSheetWithParmInTabGroup throws a runtime error and does not return a value; therefore, it is recommended that you both test the return value and wrap the function call in a try-catch block.

Usage

The first sheet opened in a main window cannot be opened using OpenSheetInTabGroup or OpenSheetWithParmInTabGroup. To create a tab group, open the first sheet as a docked sheet and then use that sheet as the siblingname argument.

The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenSheetWithParmInTabGroup, scripts for the opened sheet would check one of the following properties.

Message object property

Argument datatype

Message.DoubleParm

Double

Message.PowerObjectParm

PowerObject (PowerBuilder objects, including user-defined structures)

Message.StringParm

String


In the opened window, 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.