Progress
Programming
Handbook
Persistent Multi-window Management
An application that uses persistent multi-window management generally provides its basic application options in the default application window. These options then open one or more windows under persistent procedure control to provide functionality in addition to the default application window. All of these windows, while visible, remain available to the user in non-modal fashion. You can also provide modal capabilities anywhere in the non-modal interface using alert boxes and dialog boxes.
Creating Windows in Persistent Procedures
In general, you create and manage each persistent window using a persistent procedure. Each time you run a procedure persistently, it instantiates (creates) a context for itself. This context can include any windows that you create during instantiation. However, each persistent procedure can maintain its own current window by setting the CURRENT–WINDOW attribute of the THIS–PROCEDURE handle. This attribute overrides (but does not change) the setting of the CURRENT–WINDOW handle. If set to the widget handle of a valid window, all frames and dialog boxes defined in the procedure parent, by default, to the window specified by this attribute. Thus, a persistent procedure instance usually manages a single window in the multi-window application. For more information on procedure handles and persistent procedures, see Block Properties."
Managing Windows in Persistent Procedures
It is also often helpful to create a separate dynamic widget pool for the window you create in the persistent procedure. Usually, you want the window to exist for the life of the persistent procedure that manages it. The simplest way to guarantee this is by creating a single unnamed widget pool for the procedure. When you delete a persistent procedure that maintains its own widget pool, its persistent window is automatically deleted also. For more information on dynamic widget pools, see Using Dynamic Widgets."
Example — Persistent Multi-window Management
The following three procedures,
p-perwn1.p
,p-perwn2.p
, andp-perwn3.p
implement a small application for updating customer orders in the sports database using multiple windows. The main procedure (p-perwn1.p
) displays a browse of the customer table in the default application window. You can browse the order table for a selected customer by choosing the bOpenorders button. This creates a persistent procedure (p-perwn2.p
) that opens a child window for the order browse (p-perwn1.p
(1)):
You can repeatedly select another customer and choose the bOpenorders button to browse orders for as many customers as you want. The customer and order browses displayed for every customer all remain available to the user for input simultaneously.
This application makes ample use of procedure and SESSION handle attributes to help manage the persistent windows of the application. The main procedure uses them in two ways:
When you terminate the application by choosing the bExit button,
p-perwn1.p
calls a local internal procedure, exit–proc. After locating the first persistent procedure instance, exit–proc loops through all persistent procedures in the session and deletes each one created by the application as specified by the PRIVATE–DATA procedure handle attribute (p-perwn1.p
(3)). Note that exit–proc deletes each persistent procedure by calling the destroy–query procedure owned by the persistent procedure. This ensures that each persistent procedure manages its own resource clean-up and deletion.When you attempt to open the order browse for a customer,
p-perwn1.p
also checks to see if there is already an order browse open for that customer. It does this by looking for a persistent procedure with the customer name as part of its private data (p-perwn1.p
(4)).Note also that
p-perwn1.p
creates its own default application window instead of using the static window (p-perwn1.p
(2)). This allows the setting of the SCROLL–BARS and RESIZE window attributes.The persistent procedure,
p-perwn2.p
, displays a browse of all orders for the selected customer. Like the customer browse, you can repeatedly select orders and choose the bOpenlines button (which runsp-perwn3.p
) to browse order lines in a child window of a selected order for as many orders as you want (p-perwn2.p
(1)). Inp-perwn2.p
, you can also update each order by choosing the bUpdate button and close all orders for a customer by choosing the bClose button.Note that as persistent procedures, both
p-perwn2.p
andp-perwn3.p
are written to be run non-persistently for testing or other application purposes. This is accomplished by making some of the code conditionally executable based on the value of the PERSISTENT attribute of the THIS–PROCEDURE system handle. For example, the bClose button inp-perwn2.p
runs the destroy–query procedure or just exitsp-perwn2.p
, depending on how it is run (p-perwn2.p
(4)). You can devise many variations on this approach. One possible variation includes using the preprocessor to conditionally compile the PERSISTENT attribute tests based on whether you are compiling for a development or production environment.Each persistent procedure easily maintains the current window that it creates by setting the CURRENT–WINDOW attribute of the THIS–PROCEDURE handle (
p-perwn2.p
(3) andp-perwn3.p
(2)). Thus, there is no need to set and reset the CURRENT–WINDOW handle:
Two other important features of persistent management include setting the PRIVATE–DATA attribute and creating a widget pool so that the context of each persistent procedure can be more easily managed as a unit (
p-perwn2.p
(2) andp-perwn3.p
(1)).Like
p-perwn1.p
,p-perwn2.p
uses procedure and SESSION handle attributes:
- To delete all persistent procedures (and their windows) created for customer orders when you exit a customer order browse (
p-perwn2.p
(5))- To identify whether an order–line window has already been created for a selected order so that only one order–line browse is enabled for an order at a time (
p-perwn2.p
(6))Note that each persistent procedure has a unique destroy–query procedure. This allows any other procedure to delete the persistent procedures under its control while allowing each persistent procedure to manage its own area of control appropriately.
The persistent procedure,
p-perwn3.p
, browses and updates order lines very much likep-perwn2.p
browses and updates orders, except that it is at the bottom of the hierarchy of persistent management. When you choose the bClose button inp-perwn3.p
, destroy–query only has to delete the current instance ofp-perwn3.p
(p-perwn3.p
(3)). Depending on your application, you can also use a management model that is more or less hierarchical. Because Progress procedures are recursive, you can even create persistent procedures and windows recursively. However, there is no necessary connection between a persistent context and its recursive instance unless you establish it, for example, using the PRIVATE–DATA attribute or a shared temporary table.
To help the user manage their screen, the application organizes the windows for orders and order lines into a window family, with the customer browse window as the root (
p-perwn1.p
(1),p-perwn2.p
(3),p-perwn2.p
(1), andp-perwn3.p
(2)). Thus, the user can minimize the entire application or any order along with all of its child windows for order lines.Another feature of this application is the use of dialog boxes to provide modal functionality in an otherwise non-modal, multi-window application (
p-perwn2.p
(7) andp-perwn3.p
(4)). Thep-perwn2.p
andp-perwn3.p
procedures each use a dialog box to update the order and order–lines table, respectively. This can help to control transaction size during an update. In these examples, the transaction size is limited to a single trigger block (p-perwn2.p
(8) orp-perwn3.p
(5)). So, the update windows in this case could also be persistently managed non-modal windows without affecting the scope of transactions.Note also that these dialog boxes are parented to the window specified by the ACTIVE–WINDOW system handle (for example,
p-perwn3.p
(6)). This handle specifies the window that has received the most recent input focus in the application. Using this handle guarantees that the dialog box appears in the Progress window where the user is working, even if it is not the current window of the procedure that displays the dialog box. For more information on the ACTIVE–WINDOW handle, see Interface Design."NOTE: This example updates the qty and extended–price field in the order–line table. However, it does not update the corresponding balance field in the customer table, or the on–hand and allocated fields in the item table. You might want to add the necessary update code to maintain your working sports database. For example, you could update the customer balance field by passing the procedure handle ofp-perwn1.p
down top-perwn3.p
and calling an internal procedure inp-perwn1.p
that updates the balance field in the customer record specified by orderbuf.cust–num (inp-perwn3.p
). Calling an internal procedure inp-perwn1.p
keeps the customer table and browse management all together inp-perwn1.p
.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |