How You Can Transfer Control Between Frames
The three OpenROAD statements that create a new FrameExec object by invoking a child frame differ greatly in how control is passed to the child frame. However, all three use similar syntax to run a second frame. A simplified syntax for all three statements is:
openframe | callframe | gotoframe framename [(parameterlist)]
You can enter the
framename directly or you can use a variable to specify the frame name dynamically. Using a variable lets you specify the frame name at runtime. For an example of specifying a frame name dynamically, see
How You Can Transfer Control to a New Frame: Callframe Statement.
How You Can Pass Parameters Between Frames
When you run a frame with the openframe, callframe, or gotoframe statement, you can pass values to it with a parameter list. The syntax for the parameter list is:
parameter_name=expression{, parameter_name=expression}
parameter_name
Specifies the name of a variable in the called frame. This variable can be either a field variable or a variable that you declare in the initialize block's parameter list.
expression
Can contain constants, variables, or expressions from the calling frame. OpenROAD transfers the value of this expression to the corresponding variable in the called frame.
The following code example demonstrates opening a frame using the openframe statement. It uses the vlist table field to store information about individual videos. Every time a detail frame is opened for a particular video, the FrameExec for the detail frame is stored in the vlist[ ].details_frame. Before opening a new frame, the code checks to see whether the details frame has already been opened to avoid opening a second instance of it.
The example also illustrates how the calling frame can set an attribute (WindowTitle) of the called frame using the with clause of the openframe statement.
on click view_button =
{
if (vlist[].details_frame is null) then
vlist[].details_frame = openframe video_detail(video_info = vlist[])
with WindowTitle = vlist[].title;
else
vlist[].details_frame.BringToFront();
endif;
}
Any parameter in the called frame that you do not include in the parameter list is set to its default value.
When you pass a simple variable, such as an integer or text string, any changes made to its value in the called frame are not reflected in the calling frame. However, when you pass a 4GL object, such as a table field, you are passing a
reference to the object, not the object itself. Therefore, both the called frame and the calling frame have references to the same object, and any changes made to the object by the called frame are reflected in the calling frame as well. For more information about changing the value of a simple variable in both the calling and the called frames, see
How You Can Pass Parameters Between an Active Child and Inactive Parent.
How You Can Close a Frame
To close a frame, use the return statement. This statement closes the frame and returns control to the calling frame. The following example shows how the return statement is used to take users back to the control frame when they click the Close button or close the window:
on click close_button,
on windowclose =
begin
cleanup processing statements
return;
end
In addition, when you return from a frame invoked by the callframe statement, you can use the return statement to pass a return value back to the calling frame.
For more information about returning from the openframe, callframe, and gotoframe statements, see the following sections:
A return statement for the starting frame of the application closes all frames in the application and returns control to the level where the user entered the application. To allow users to return to the operating system, the starting frame for your application should include a Quit operation (either as a menu operation or a button) that executes the return statement. For more information about the return statement, see the Language Reference Guide.
If there is some reason for the user to be able to leave the application from a frame other than the starting frame, use the exit statement. This statement closes all open frames and returns control to the level where the user entered the application. For more information about the exit statement, see the Language Reference Guide.