OpenSheet
PowerScript function
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
|
1 |
OpenSheet ( sheetrefvar {, windowtype }, mdiframe {, position {, arrangeopen } } ) |
|
Argument |
Description |
|---|---|
|
sheetrefvar |
The name of any window variable that is not an MDI frame |
|
windowtype (optional) |
A string whose value is the datatype of the window you |
|
mdiframe |
The name of an MDI frame window. |
|
position (optional) |
The number of the menu item (in the menu associated with |
|
arrangeopen (optional) |
A value of the ArrangeOpen enumerated datatype specifying
|
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
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 try |
This 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:
|
1 2 |
window child OpenSheet(child, "child_1", MDI_User, 4, Layered!) |
See also