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.
Controls
Window objects
Syntax
|
1 |
<span>OpenSheet</span> ( <span>sheetrefvar</span> {, <span>windowtype</span> }, <span>mdiframe</span> {, <span>position</span> <br> {, <span>arrangeopen</span> } } ) |
|
Argument |
Description |
|---|---|
|
sheetrefvar |
The name of any window variable that |
|
windowtype (optional) |
A string whose value is the datatype |
|
mdiframe |
The name of an MDI frame window. |
|
position (optional) |
The number of the menu item (in the menu |
|
arrangeopen (optional) |
A value of the ArrangeOpen enumerated
|
Return Values
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 PowerBuilder 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 |
integer li_return<br>try<br>   li_return = <span>Opensheet</span> (child_1, MDI_User, 2, &<br>      Original!)<br>   if IsNull(li_return) then<br>       MessageBox ("Failure", "Null argument provided")<br>   elseif li_return= 1 then<br>       MessageBox ("Success", "Sheet opened.")<br>   else<br>       MessageBox ("Failure", "Sheet open failed.")<br>   end if<br>catch (runtimeerror rt)<br>   Messagebox("Failure","Sheet open failed. " &<br>      + rt.getmessage()) //Handle the error or not<br>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 |
window child |
|
1 |
<span>OpenSheet</span>(child, "child_1", MDI_User, 4, Layered!) |