SET(WIDGET_CALL_DATA)
Allows you to create a template telling VAXTPU 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 VAXTPU 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 DWT$C_CRHELP_REQUESTED.
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
VAXTPU data type to which VAXTPU 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 VAXTPU, for each field of the
structure, what data type the field has originally
and what VAXTPU 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 VAXTPU 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, VAXTPU
interprets the data in the callback structure according to the
description you create.
In an application layered on VAXTPU, 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, VAXTPU 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. For more information on the fields in each widget's callback
structures, see the VMS DECwindows Toolkit Routines Reference Manual.
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
VAXTPU.
Although you can skip trailing fields, you cannot skip intermediate
fields even if they are unimportant to your application. To direct
VAXTPU to ignore the information in a given field, use the request
string "void" and the keyword UNSPECIFIED when specifying that field.
If you specify an invalid request string, VAXTPU signals
TPU$_ILLREQUEST. If you specify an invalid keyword, VAXTPU signals
TPU$_AMBIGSYMUSED. If you use valid parameters but assign the wrong
data type to a field and if VAXTPU detects the error, VAXTPU assigns
the data type UNSPECIFIED to that field during processing of a
callback.
For more information on how SET (WIDGET_CALL_DATA) affects GET_INFO
(WIDGET, "callback_parameters"), see the help topic GET_INFO(WIDGET) or
the VAX 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 VAXTPU 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 VAXTPU 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)