CREATE_WIDGET

     Has two variants.  One variant creates a heirarchy of widgets (as
     defined in a Resource Manager database) and returns the topmost widget.
     The other variant creates and returns a widget using the intrinsics or
     a Toolkit low-level creation routine.

     Syntax

     widget := CREATE_WIDGET (widget_class, widget_name,
                              {parent_widget | SCREEN}
                              [, program_source [, closure
                              [, widget_arguments]]])

     Creates the widget instance you specify, using the intrinsics of a
     Toolkit low-level creation routine.

     widget := CREATE_WIDGET (resource_mngr_identifier_name,
                              resource_mngr_hierarchy_id,
                              {parent_widget | SCREEN}
                              [, program_source [, closure]])

     Creates and returns a widget instance.  This variant creates an entire
     hierarchy of widgets (as defined in a Resource Manager database) and
     returns the topmost widget.  All of the children of the returned widget
     are also created.  The topmost widget is not managed.  If you specify
     one or more callback arguments in your User Interface Language (UIL)
     file, specify either the routine TPU$WIDGET_INTEGER_CALLBACK or the
     routine TPU$WIDGET_STRING_CALLBACK.

  Parameters

     widget_class                   The integer returned by
                                    DEFINE_WIDGET_CLASS that specified the
                                    class of widget to be created.

     widget_name                    A string that is the name to be given to
                                    the widget.

     parent_widget                  The widget that is to be the parent of
                                    the newly created widget.  Specify the
                                    third parameter to CREATE_WIDGET as a
                                    widget if the parent for the
                                    newly-created widget already exists and
                                    is not TPU's main window widget.

     SCREEN                         A keyword indicating that the newly
                                    created widget is to be the child of
                                    TPU's main window widget.

     program_source                 A string, buffer, range, learn or
                                    program specifying the interface
                                    callback.  This code is executed when
                                    the widget performs a callback to
                                    TPU.

     closure                        The closure value can be any string or
                                    integer value you want.  TPU simply
                                    passes the value to the application when
                                    the widget performs a callback to
                                    TPU.

     widget_arguments               A series of pairs of resource names and
                                    resource values, passed as arrays or as
                                    string/value pairs.  For more
                                    information on specifying this
                                    parameter, see the documentation for
                                    DECwindows TPU.

     resource_mngr_identifier_name  A case-sensitive string that is the name
                                    assigned to the widget in the UIL file
                                    defining the widget.

     resource_mngr_hierarchy_id     The hierarchy identifier returned by the
                                    built-in SET (UID).  This identifier is
                                    passed to the Resource Manager, which
                                    uses the identifier to find the resource
                                    name in the database.

  Comments

     The case of the widget's name that you specify as a parameter to
     CREATE_WIDGET must be the same as the case of a widget's name in the
     User Interface Definition (UID) file, if there is an accompanying UID
     file.

  Example

     The following procedure creates a modal dialog box widget and maps the
     widget to the TPU screen, if the procedure "user_callback_routine"
     is a valid callback routine and if there is an accompanying UIL file
     defining the modal dialog box.  To see such a UIL file, refer to the
     documentation for DECwindows TPU.

     PROCEDURE user_create_dialog_box

     LOCAL example_widget,
           example_widget_name,
           example_widget_hierarchy;

     example_hierarchy := SET (UID, "
     mynode$dua0:[smith]example
     ");
     example_widget_name := "EXAMPLE_BOX";   ! The widget EXAMPLE_BOX is
                                             ! defined in the UIL file.
     IF GET_INFO (example_widget, "type") <> WIDGET
     THEN
         example_widget := CREATE_WIDGET (example_widget_name,
                                          example_hierarchy,
                                          SCREEN, "user_callback_routine");
     ENDIF;
     MANAGE_WIDGET (example_widget);
     RETURN (TRUE);

     ENDPROCEDURE;

     To see an example of how to use the variant of CREATE_WIDGET that calls
     the Toolkit low-level creation routine, see the DECwindows TPU
     documentation.

  Related Topics

     DELETE   LOWER_WIDGET   MANAGE_WIDGET     MAP
     RAISE_WIDGET   SET(MAPPED_WHEN_MANAGED)   UNMANAGE_WIDGET
     UNMAP