Description
Opens a sheet within an MDI (multiple document interface) frame window and creates a menu item for selecting the sheet on the specified menu.
Applies to
Window objects
Syntax
OpenSheet ( sheetrefvar {, windowtype }, mdiframe {, position {, arrangeopen } } )
|
Argument |
Description |
|---|---|
|
sheetrefvar |
The name of any window variable that is not an MDI frame window. OpenSheet places a reference to the open sheet in sheetrefvar. |
|
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. |
|
mdiframe |
The name of an MDI frame window. |
|
position (optional) |
The number of the menu item (in the menu associated with the sheet) to which you want to append the names of the open sheets. Menu bar menu items are numbered from the left, beginning with 1. The default value of 0 lists the open sheets under the next-to-last menu item. |
|
arrangeopen (optional) |
A value of the ArrangeOpen enumerated datatype specifying how you want the sheet arranged in the MDI frame in relation to other sheets when it is opened:
|
Return value
Integer.
Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenSheet returns null. In some cases, such as if the windowtype argument is invalid, OpenSheet 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 as shown in the first example in the Examples section.
Usage
A sheet is a document window that is contained within an MDI frame window. MDI applications allow several sheets to be open at the same time. The newly opened sheet becomes the active sheet. If the opened sheet has an associated menu, that menu becomes the menu at the top of the frame.
When you specify windowtype, the window object specified in windowtype must be the same datatype as sheetrefvar (a datatype includes datatypes inherited from it). The datatype of sheetrefvar is usually window, from which all windows are inherited, but it can be any ancestor of windowtype. If it is not the same type, an execution error occurs.
PowerBuilder does not automatically copy objects that are dynamically referenced (through string variables) into your executable. To include the window object specified in windowtype in your application, list it in the resource (PBR) file that you use when you build the executable. For more information about PBR files for an executable, see the section called “Using PowerBuilder resource files” in Users Guide.
OpenSheet opens a sheet and appends its name to the item on the menu bar specified in position. If position is 0 or greater than the number of items on the menu bar, PowerBuilder appends the name of the sheet to the next-to-last menu item in the menu bar. In most MDI applications, the next-to-last menu item on the menu bar is the Window menu, which contains options for arranging sheets, as well as the list of open sheets.
PowerBuilder cannot append the sheets to a menu that does not have any other menu selections. Make sure that the menu you specify or, if you leave out position, the next-to-last menu, has at least one other item.
If more than nine sheets are open in the frame, the first nine are listed on the menu specified by position and a final item More Windows is added.
Sheets in a frame cannot be made invisible. When you open a sheet, the value of the Visible property is ignored. Changing the Visible property when the window is already open has no effect.
Opening response windows
Do not use the OpenSheet function to open a response window.
Examples
This example opens the sheet child_1 in the MDI frame MDI_User in its original size. It appends the name of the opened sheet to the second menu item in the menu bar, which is now the menu associated with child_1, not the menu associated with the frame. OpenSheet might return -1 or throw a runtime error if the call fails. To ensure that both of these possibilities are trapped, this example checks the return value of the function and uses a try-catch statement to catch a possible runtime error:
integer li_return
try
li_return = Opensheet (child_1, MDI_User, 2, &
Original!)
if IsNull(li_return) then
MessageBox ("Failure", "Null argument provided")
elseif li_return= 1 then
MessageBox ("Success", "Sheet opened.")
else
MessageBox ("Failure", "Sheet open failed.")
end if
catch (runtimeerror rt)
Messagebox("Failure","Sheet open failed. " &
+ rt.getmessage()) //Handle the error or not
end tryThis example opens an instance of the window object child_1 as an MDI sheet and stores a reference to the opened window in child. The name of the sheet is appended to the fourth menu associated with child_1 and is layered:
window child OpenSheet(child, "child_1", MDI_User, 4, Layered!)
See also
