Enhancements to Portlet Guest Frame Blocking and Shielding

By default, when OpenROAD executes an event block or a called procedure in a frame, activity in other active frames is blocked. The user cannot perform any actions until the event block or procedure completes.

When blocking occurs, by default all the active frame windows also become shielded (the topmost window [frame] in each application frame stack is the stack’s active window [frame]). New frame stacks within a running application are created when the 4GL OPENFRAME statement is called.

The previous implementation of portlets led to a situation when a script invoked by a portlet field performs a CALLFRAME to create a new frame that becomes the topmost window within the application stack that issued the CALLFRAME. As expected, the frame displayed and activated by the CALLFRAME blocked the calling frame and shielded it. Because the frame that invoked the CALLFRAME was a "guest" frame, meaning that it was a different frame from the frame that displayed the portlet (that is, the portlet’s host), the guest was therefore inert in that all fields within it were disabled (inactive) and the "wait" cursor was displayed whenever the mouse cursor was placed above the frame or any of its fields.

If the guest frame was invisible (that is, the FRAMEEXEC WindowVisiblity attribute was set to WV_INVISIBLE), this behavior was unnoticeable. The frame hosting the portlet was not, generally, blocked. All fields within the host were still active, except the portlet field which activated the script that generated the CALLFRAME. These active fields within the host were able to respond to user interactions that could trigger 4GL scripts. Furthermore, the portlet that caused the CALLFRAME would still respond to user interactions (like button clicks) but, because the portlet’s original frame (the guest) was blocked, the guest would not respond to any events from the portlet until the frame called by the guest was closed. In essence, it appeared that while the guest’s CALLFRAME was active all portlet events would be "queued" until the CALLFRAME completed.

Previously, this portlet behavior and how it related to the host frame could be tailored by setting the field biases of the various fields within the host to inactive biases (for example, FB_LANDABLE) prior to the portlet-activated script performing a CALLFRAME, then setting the relevant field biases of the host fields back to an active bias (for instance, FB_CHANGEABLE) after the CALLFRAME returns. The programmer could disable and enable the portlet’s "host field" alone. (The host field is the field within the host that contains the portlet.) By manipulating the portlet’s host field bias, the portlet could be disabled and enabled simply and independently of other fields on the host frame. This may not have sufficed because:

In this version of OpenROAD, you can now perform a CALLFRAME as the result of a portlet interaction (where the CALLFRAME is issued from a guest frame) and optionally receive the same runtime and visual behavior as if the CALLFRAME was the result of a non-portlet field interaction—the simple case where portlets are not used. The called frame (through the CALLFRAME 4GL statement) will block the guest frame and optionally the portlet’s host frame.

A new attribute was added to the ProcExec system class (which is an ancestor to both GhostExec and FrameExec classes): PortletBlocking. If a FrameExec’s PortletBlocking attribute is set to PB_HOSTFRAME, the FRAMEEXEC—when activated and displayed through a CALLFRAME—will block interactions with the portlet’s host and guest frames and display the "wait" cursor whenever the mouse pointer is above any of these frame’s fields.

The following are possible values for the PortletBlocking attribute:

In the following example, the mouse pointer is over a portlet field (guest field) in the portlet host frame. Portlet field-activated events and scripts are deferred until after the blocking frame is closed.

In the following example, the mouse pointer is over a non-portlet field in the portlet host frame. The non-portlet field is blocked (disabled) and shielded (the wait cursor is displayed).

In the following example, the mouse pointer is over a portlet field (guest field) in the portlet host frame. The non-portlet field is blocked (disabled) and shielded (the wait cursor is displayed).

• PB_GUESTFIELD (value = 2) – The hosted portlet field (guest field) becomes inactive (disabled) and shielded (a "wait" cursor is displayed when the mouse pointer is over them). The guest frame is blocked and shielded. The host frame and its fields (except the hosted portlet field) are not blocked or shielded.

In the following example, the mouse pointer is over a portlet field (guest field) in the portlet host frame. The non-portlet field is blocked (disabled) and shielded (the wait cursor is displayed).

The PortletBlocking attribute can also be set on a CALLFRAME-by-CALLFRAME basis by using "WITH PortletBlocking = value" as a modifier to the CALLFRAME command.

For more information about the ProcExec.PortletBlocking attribute, see the Language Reference Guide.

To help developers who are implementing applications that use portlets, a new environment variable was created: II_W4GL_PORTLETBLOCKING_DEFAULT. Any application started with this environment variable set will use the environment variable setting as the portlet blocking default for all CALLFRAME statements issued from within a portlet script.

Because this environment variable is only checked at application startup, changing its value within an application will have no effect. Valid values are listed in Environment Variables.