Progress
Programming
Handbook


Dynamic Widgets

You can describe and immediately instantiate any dynamic widget with a CREATE Widget statement, which has the following general syntax:

SYNTAX
CREATE widget-type handle-variable 
  [ IN WIDGET-POOL pool-name ]
  [ ASSIGN attribute = value [ attribute = value ] ... ]
  { [ trigger-phrase ] } 

The widgettype parameter is the name of the widget type, such as WINDOW, FRAME, or BUTTON, and the handlevariable parameter is the name of a variable of type WIDGET–HANDLE that receives the widget handle value for the widget.

The poolname parameter specifies a previously created widget pool. A widget pool allows you to manage a set of dynamic widgets as a group. For more information on creating and using widget pools, see Using Dynamic Widgets."

The attribute parameter is the name of a widget attribute that is valid for the widget. Unlike static widgets, which you describe using compile-time options, you must describe a dynamic widget by setting its attributes at run time. You can set attributes when or after you create the widget. For more information on setting widget attributes, see the "Widget Attributes" section.

The triggerphrase specifies one or more triggers for the widget. Note that the ON statement provides a more flexible technique for specifying triggers. The scoping is more reliable and allows the CREATE Widget statement to be shorter and more readable. For more information, see the "User-interface Triggers" section.

You can use this syntax to create any dynamic widget. You can create any type of widget dynamically except literal, down frame, and browse widgets. Literal widgets are created only by Progress to hold side labels for static data-representation widgets. Down frames and browse widgets provide different techniques for displaying multiple iterations of data. Progress requires compile-item information to create these widgets. For more information on down frames, see Frames." For more information on browse widgets, see Using the Browse Widget."

Referencing Dynamic Widgets

Note that unlike static widgets, a dynamic widgets are created and referenced only with widget-handle variables. This is because you are describing an actual instance of the widget, independent of any other widget. A dynamic widget stands on its own, whether or not it requires a container widget to be part of the user interface. Note also that dynamic data-representation widgets, such as fill-in fields, have no underlying field or variable for data storage. You must explicitly associate a dynamic widget with a field or variable by assigning data between the widget’s SCREEN–VALUE attribute and any appropriate field or variable.

Deleting Dynamic Widgets

You can explicitly delete a dynamic widget with the DELETE WIDGET statement:

SYNTAX
DELETE WIDGET widget-handle 

If you do not explicitly delete a widget, it remains allocated until the end of the session or until the widget pool that contains it is deleted. If you delete a dynamic container widget, such as a frame or window, any dynamic widgets that it contains are deleted also.

An advantage of dynamic widgets is that you can determine the number of widgets to create at run time. For example, you might create a button for each table in a database or each record in a table. A disadvantage is that you must do more of the work for dynamic widgets. For example, Progress can automatically lay out static widgets in a frame, but you must explicitly position dynamic widgets.

NOTE: The Procedure Editor optionally deletes all dynamic widgets that you create in a session each time you return to the Editor after running an application. For more information, see the on-line help for the Procedure Editor, and Progress Basic Development Tools manual (Character only).

You can also delete groups of dynamic widgets in a widget pool using the DELETE WIDGET–POOL statement. For more information, see Using Dynamic Widgets."

The following procedure creates a dynamic button for each record in the salesrep table:

p-dybuts.p
DEFINE VARIABLE num-buts  AS INTEGER.
DEFINE VARIABLE temp-hand AS WIDGET-HANDLE.

DEFINE FRAME butt-frame
   WITH WIDTH 60 CENTERED TITLE "Sales Representatives".

FORM
   salesrep
   WITH FRAME rep-frame.

num-buts = 0.
FOR EACH salesrep:
   CREATE BUTTON temp-hand
         ASSIGN LABEL = salesrep.sales-rep
                FRAME = FRAME butt-frame:HANDLE
                ROW = TRUNC(num-buts / 3, 0) + 1
                COLUMN = ((num-buts MOD 3) * 20) + 1
                SENSITIVE = TRUE
         TRIGGERS:
            ON CHOOSE
               DO:
                 FIND salesrep WHERE salesrep.sales-rep = SELF:LABEL.
                 DISPLAY salesrep WITH FRAME rep-frame.
               END.
         END TRIGGERS.
   num-buts = num-buts + 1.
END.

FRAME butt-frame:HEIGHT-CHARS = (num-buts / 3) + 2.

VIEW FRAME butt-frame.

WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW. 

Note that within the CREATE BUTTON statement, the procedure assigns the button to butt–frame, then calculates a ROW and COLUMN value within that frame. The procedure must explicitly set the width of the frame in the DEFINE FRAME statement and set the height of the frame after all the buttons are created. By contrast, Progress automatically positions the static widgets within rep–frame and makes that frame the proper size.

For more information on creating and using dynamic widgets, see Using Dynamic Widgets."


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095