TPUHELP.HLB  —  SET(WIDGET_CALL_DATA)
  SET(WIDGET_CALL_DATA)

     Allows you to create a template telling DECTPU how to interpret the
     information in the fields of a widget's callback data structure.

  Syntax

     SET (WIDGET_CALL_DATA, widget, reason_code,
          request_string, keyword [, request_string, keyword...])

  Parameters

     WIDGET_CALL_DATA     A keyword indicating that the SET built-in is
                          being used to control how DECTPU interprets
                          information in a widget's callback data structure.

     widget               The specific widget instance for which you want to
                          determine how the callback data are interpreted.

     reason_code          The identifier for the reason code with which the
                          callback data structure is associated.  For
                          example, if you are using SET (WIDGET_CALL_DATA)
                          to set the format of the callback structure
                          associated with the Help Requested reason code of
                          the File Selection widget, and if your program
                          defines the VAX reason code bindings as constants,
                          you could refer to the Help Requested reason code
                          by using the constant XmCR_HELP.

     request_string       One of the six valid strings describing the data
                          type of a given field in a callback data
                          structure.  The valid strings are as follows:

                             "char"                 "short"
                             "compound_string"      "void"
                             "int"                  "widget"

     keyword              One of the four valid keywords indicating the
                          DECTPU data type to which DECTPU should convert
                          the data in a given field of a callback data
                          structure.  The valid keywords are as follows:

                             INTEGER                UNSPECIFIED
                             STRING                 WIDGET

                          Use the request_string parameter with the keyword
                          parameter to inform DECTPU, for each field of the
                          structure, what data type the field has originally
                          and what DECTPU data type corresponds to the
                          original data type.  The valid keywords
                          corresponding to each request string are as
                          follows:

                             Request String       Valid Corresponding Keywords
                             --------------       ----------------------------
                             "char"               STRING  or UNSPECIFIED
                             "compound_string"    STRING  or UNSPECIFIED
                             "int"                INTEGER or UNSPECIFIED
                             "short"              INTEGER or UNSPECIFIED
                             "void"                          UNSPECIFIED
                             "widget"             WIDGET  or UNSPECIFIED

  Comments

     You use SET (WIDGET_CALL_DATA) to tell DECTPU what data type to ascribe
     to each field in the callback data structure associated with a given
     callback reason of a given widget instance.  During a callback
     generated by the specified widget for the specified reason, DECTPU
     interprets the data in the callback structure according to the
     description you create.

     In an application layered on DECTPU, you can obtain the interpreted
     callback data by using the built-in GET_INFO (WIDGET,
     "callback_parameters").

     You can create a different template for each of the reason codes
     associated with a given widget.  To do so, make a separate call to the
     SET (WIDGET_CALL_DATA) built-in for each reason code.  If you specify
     the same widget and reason code in more than one call, DECTPU uses the
     most recently specified format.

     In all callback data structures defined by the DECwindows Toolkit, the
     first field is the reason field and the second field is the event
     field.  If your application creates and uses a new kind of widget, the
     widget's callback structure must follow this convention.

     Do not specify any request string or keyword for the reason field.  In
     almost all cases, you specify the event field with the request string
     "void" and the keyword UNSPECIFIED.  Specify all subsequent fields, if
     the callback structure has such fields, up to and including the last
     field you want to specify.  Note that the VAX longword data type
     corresponds to the "int" request string and the INTEGER data type in
     DECTPU.

     Although you can skip trailing fields, you cannot skip intermediate
     fields even if they are unimportant to your application.  To direct
     DECTPU to ignore the information in a given field, use the request
     string "void" and the keyword UNSPECIFIED when specifying that field.

     For more information on how SET (WIDGET_CALL_DATA) affects GET_INFO
     (WIDGET, "callback_parameters"), see the help topic GET_INFO(WIDGET) or
     the DEC Text Processing Utility Manual.

  Example

     The following code fragment begins by defining the constant
     DWT$C_CRSINGLE to be the integer value 20, which is the integer
     associated with the reason "user selected a single item." The next
     statement tells DECTPU how to interpret the fields of the callback data
     structure associated with a List Box widget assigned to the variable
     "initial_list_box".  The statement directs DECTPU to ignore the data in
     the "event" field and to treat the data in the item field as type
     STRING, in the "item length" field as type INTEGER, and the "item
     number" field as type INTEGER.

     CONSTANT DWT$C_CRSINGLE := 20;

     SET (WIDGET_CALL_DATA, initial_list_box, DWT$C_CRSINGLE,
          "void",            UNSPECIFIED,  ! event
          "compound_string", STRING,       ! item
          "int",             INTEGER,      ! item length
          "int",             INTEGER);     ! item number

  Related Topics

     GET_INFO(WIDGET)    SET(WIDGET_CALLBACK)
Close Help