Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

The following example results in a traceback display when the procedure is executed and traceback is enabled:

#2
PROCEDURE traceback_example SET (TRACEBACK, ON); SET (TRACEBACK, BELL); RETURN 5; ENDPROCEDURE; PROCEDURE call_example traceback_example; ENDPROCEDURE;

Invoking the procedure CALL_EXAMPLE results in the following traceback:

BELL is an invalid keyword Occurred in builtin SET At line 2 Called from builtin EXECUTE Called from line 22 of procedure EVE_TPU Called from line 1 Called from builtin EXECUTE Called from line 96 of procedure EVE$PROCESS_COMMAND Called from line 3 of procedure EVE$PARSER_DISPATCH Called from line 97 of procedure EVE$$EXIT_COMMAND_WINDOW Called from line 2

Format

integer := SET (UID, filespec [[, filespec... ]])

Parameter

filespec

A string that specifies the UID file to be used. DECTPU does not apply a default file specification to the UID file specification. You must specify at least one file name.

Return Value

Description

The SET (UID) procedure sets the User Interface Definition (UID) file or files to be used with DECTPU. This built-in is preferred over the SET (DRM_HIERARCHY) built-in procedure. Using UID files to specify hierarchies makes it easy to translate the product into other languages and to modify an application's interface without recompiling all the code that implements the application.

SET (UID) is similar to SET (DRM_HIERARCHY). However, SET (UID) is the preferred form.

For more information about UID files, see the VMS DECwindows Guide to Application Programming.

Signaled Errors

• TPU$_ARGMISMATCH	ERROR	The data type of the indicated parameter is not supported by the SET (UID) built-in.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (UID) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (UID) built-in.
  TPU$_FAILURE_STATUS	ERROR	The Digital Resource Manager returned an error status.
  TPU$_INVPARAM	ERROR	You specified an invalid parameter.
  TPU$_REQUIRESDECW	ERROR	Requires the DECTPU DECwindows screen updater.

Example

The following example designates the User Interface Definition (UID) file MYNODE$DUA0:[SMITH]EXAMPLE.UID as a file to be used with DECTPU to create widgets needed by the layered application:

example_hierarchy := SET (UID, "mynode$dua0:[smith]example.uid"); 
 
      

Format

SET (UNDEFINED_KEY, string1

• ,
  • buffer
  • learn_sequence
  • program
  • range
  • string2

)

Parameters

UNDEFINED_KEY

A keyword that specifies that SET is to determine the action taken when an undefined key is pressed.

string1

A string that specifies the key map list for which this procedure is called.

buffer

The buffer that contains DECTPU statements that specify the action to be taken if you press an undefined key. SET (UNDEFINED_KEY) compiles the statements in the buffer and stores the resulting program in the specified key map list.

learn_sequence

The learn sequence that specifies the action to be taken if you press an undefined key. The contents of a variable of type learn do not require compilation. SET (UNDEFINED_KEY) stores the learn sequence in the specified key map list.

program

The program that specifies the action to be taken if you press an undefined key. The contents of a variable of type program do not require compilation. SET (UNDEFINED_KEY) stores the program in the specified key map list.

range

The range that contains DECTPU statements that specify the action to be taken if you press an undefined key. SET (UNDEFINED_KEY) compiles the statements in the range and stores the resulting program in the specified key map list.

string2

The string that contains DECTPU statements that specify the action to be taken if you press an undefined key. SET (UNDEFINED_KEY) compiles the statements in the string and stores the resulting program in the specified key map list.

Description

The SET (UNDEFINED_KEY) procedure determines the action taken when an undefined key is pressed.

If the third parameter is not specified, DECTPU displays the message "key has no definition" when you press an undefined key.

Signaled Errors

• TPU$_NOKEYMAPLIST	WARNING	You attempted to access an undefined key map list.
  TPU$_TOOFEW	ERROR	SET (UNDEFINED_KEY) requires at least two parameters.
  TPU$_TOOMANY	ERROR	SET (UNDEFINED_KEY) accepts no more than three parameters.
  TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.
  TPU$_ARGMISMATCH	ERROR	The second parameter must be a string.

Example

The following example causes the default undefined key message to be displayed when an undefined key is entered:

IF GET_INFO ("tpu$key_map_list", "undefined_key") <> 0 
THEN 
    SET (UNDEFINED_KEY, "tpu$key_map_list"); 
ENDIF; 
 
      

Format

SET (VIDEO, window,

• BLINK
• BOLD
• REVERSE
• UNDERLINE
• NONE

)

Parameters

VIDEO

The video attributes of a window.

window

The window in which a video attribute is being set.

BLINK

Causes the characters in the window to blink.

BOLD

Causes the characters in the window to be bolded.

REVERSE

Causes the characters in the window to be displayed in reverse video.

UNDERLINE

Causes the characters in the window to be underlined.

NONE

Applies no video attributes to the characters in the window. This is the default.

Description

The SET (VIDEO) procedure sets the video attributes, which are cumulative, for a window. The window assumes the video attribute of each video keyword that you use with SET (VIDEO) during an editing session. If you want to change the video attribute of a window, and you do not want the cumulative effect of previous attributes, use SET (VIDEO, window, NONE) before specifying the new attribute. SET (VIDEO, window, NONE) turns off all video attributes for a window.

The video attribute is applied during the next screen update. The screen manager repaints the window to apply the video attributes, even if the cumulative effect of your changes has been to leave the video attributes the same.

SET (VIDEO) does not affect the status line of a window. You can specify a video attribute for a status line either with CREATE_WINDOW or with the SET (STATUS_LINE) built-in procedure. When the window and the status line have different video attributes, you can use the status line to separate multiple windows on the screen or to highlight status information.

Signaled Errors

Example

The following example causes the current window to be displayed in reverse video and with underlining:

SET (VIDEO, CURRENT_WINDOW, REVERSE); 
SET (VIDEO, CURRENT_WINDOW, UNDERLINE); 
 
      

Format

SET (WIDGET, widget,

• widget_args [[, widget_args... ]]

)

Parameters

WIDGET

A keyword that directs DECTPU to set an attribute of a widget.

widget

The widget whose values you want to set.

widget_args

One or more pairs of resource names and resource values.

You can specify a pair as an array or as a pair of separate parameters. If you use an array, you index the array with a string that is the name of the resource you want to set. Resource names are case sensitive. The corresponding array element contains the value you want to assign to that resource. The array can contain any number of elements. If you use a pair of separate parameters, use the following format:

resource_name_string, resource_value

Arrays and string/value pairs may be interspersed. Each array index and its corresponding element value, or each string and its corresponding value, must be valid widget arguments for the class of widget whose resources you are setting.

Description

With the SET (WIDGET) procedure, you can assign values to various resources of a widget. SET (WIDGET) is functionally equivalent to the X Toolkit routine XtSetValues.

If you specify the name of a resource that the widget does not support, DECTPU signals the error TPU$_NONAMES.

For more information about specifying resources, see the Guide to the DEC Text Processing Utility.

Signaled Errors

• TPU$_BADKEY	WARNING	You specified an invalid keyword as a parameter.
  TPU$_ARGMISMATCH	ERROR	You specified a value whose data type is not supported.
  TPU$_NONAMES	WARNING	You specified an invalid widget resource name.
  TPU$_NORETURNVALUE	ERROR	SET (WIDGET) cannot return a value.
  TPU$_REQUIRESDECW	ERROR	You can use the SET (WIDGET) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (WIDGET) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (WIDGET) built-in.

Example

The following example sets the "value" resource of the current window's scroll bar widget to 100. This causes the scroll bar slider to be displayed as far toward the bottom of the scroll bar widget as possible.

scroll_bar_widget := SET (SCROLL_BAR, CURRENT_WINDOW, VERTICAL, ON); 
SET (WIDGET, scroll_bar_widget, "value", 100); 
 
      

Format

SET (WIDGET_CALLBACK, widget,

• buffer
• learn_sequence
• program
• range
• string

, closure )

Parameters

WIDGET_CALLBACK

A keyword that directs DECTPU to set the application-level widget callback.

widget

The widget whose callback you want to set.

buffer

The buffer that contains the application-level callback routine. This code is executed when the widget performs a callback to DECTPU.

learn_sequence

The learn sequence that specifies the application-level callback routine. This code is executed when the widget performs a callback to DECTPU.

program

The program that specifies the application-level callback routine. This code is executed when the widget performs a callback to DECTPU.

range

The range that contains the application-level callback routine. This code is executed when the widget performs a callback to DECTPU.

string

The string that contains the application-level callback routine. This code is executed when the widget performs a callback to DECTPU.

closure

A string or integer. DECTPU passes the value to the application when the widget performs a callback to DECTPU. DECwindows documentation refers to closures as tags. For more information about using closures, see the Guide to the DEC Text Processing Utility.

Description

The SET (WIDGET_CALLBACK) procedure specifies the DECTPU program or learn sequence to be called by DECTPU when a widget callback occurs for the widget.

Signaled Errors

• TPU$_ARGMISMATCH	ERROR	The data type of the indicated parameter is not supported by the SET (WIDGET_CALLBACK) built-in.
  TPU$_BADDELETE	ERROR	You are attempting to modify an integer, a keyword, or a string constant.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (WIDGET_CALLBACK) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (WIDGET_CALLBACK) built-in.
  TPU$_COMPILEFAIL	WARNING	Program compilation has been terminated because of a syntax error.
  TPU$_REQUIRESDECW	ERROR	You can use SET (WIDGET_CALLBACK) only if you are using DECwindows DECTPU.

Example

The following example designates the EVE procedure EVE$SCROLL_DISPATCH as the callback routine for the widget scroll_bar_widget and assigns to the callback the closure value 'h':

SET (WIDGET_CALLBACK, scroll_bar_widget, "eve$scroll_dispatch", 'h'); 
 
      

Format

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

Parameters

WIDGET_CALL_DATA

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

widget

The specific widget 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 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 reason code by using the constant XmCR_HELP for DECwindows.

request_string

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

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

keyword

One of the four valid keywords that indicates 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	STRING
UNSPECIFIED	WIDGET

Use the request_string parameter with the keyword parameter to inform DECTPU, for each field of the structure, what data type the field had 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	Associated Keyword(s)
"widget"	WIDGET or UNSPECIFIED
"short"	INTEGER or UNSPECIFIED
"int"	INTEGER or UNSPECIFIED
"compound_string"	STRING or UNSPECIFIED
"char"	STRING or UNSPECIFIED
"void"	UNSPECIFIED

Description

With the SET (WIDGET_CALL_DATA) procedure, you can create a template that tells DECTPU how to interpret the information in the fields of a widget's callback data structure. You use SET (WIDGET_CALL_DATA) to tell DECTPU what data type to assign to each field in a callback data structure. You must specify the widget and the callback reason whose data structure you want DECTPU to process. 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 get the interpreted callback data by using the GET_INFO (WIDGET, "callback_parameters") built-in procedure.

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 procedure 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 code 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 or 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 UNSPECIFIED keyword. Specify all subsequent fields, if the callback structure has such fields, up to and including the last field you want to specify. 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 UNSPECIFIED keyword when specifying that field.

If you specify an invalid request string, DECTPU signals TPU$_ILLREQUEST. If you specify an invalid keyword, DECTPU signals TPU$_BADKEY. If you use valid parameters but assign the wrong data type to a field and if DECTPU detects the error, DECTPU assigns the data type UNSPECIFIED to that field while processing a callback.

An application should use this built-in only if it needs access to callback information other than the reason code. For more information on how SET (WIDGET_CALL_DATA) affects GET_INFO (WIDGET, "callback_parameters"), see the online Help topic GET_INFO(WIDGET).

Signaled Errors

• TPU$_BADKEY	WARNING	You specified an invalid keyword as a parameter.
  TPU$_REQUIRESDECW	ERROR	You can use this built-in only if you are using DECwindows DECTPU.
  TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (WIDGET-CALL_DATA) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (WIDGET-CALL_DATA) built-in.

Example

The following example begins by defining the constant APP$C_CRSINGLE to be the integer value 23, which is the integer associated with the reason "user selected a single item":

CONSTANT APP$C_CRSINGLE := 23; 
 
SET (WIDGET_CALL_DATA, initial_list_box, APP$C_CRSINGLE, 
     "void",            UNSPECIFIED,  ! event 
     "compound_string", STRING,       ! item 
     "int",             INTEGER,      ! item length 
     "int",             INTEGER);     ! item number 
 
      

The file DECW$INCLUDE:XM.H contains constants defined for callback reason codes. If you layer an application, the values you assign to the reason code constants must match the values in this file.

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.

Format

SET (WIDGET_CONTEXT_HELP, widget,

• ON
• 1
• OFF
• 0

)

Parameters

WIDGET_CONTEXT_HELP

A keyword that directs DECTPU to enter the DECwindows context-sensitive help mode in which the mouse pointer changes to a question mark until you click MB1 on a widget. The mouse pointer then reverts to the default pointer shape, and a help callback is called on the selected widget (or its parent if the selected widget has no help callback).

widget

Specifies the widget within which modal help interaction will be limited. Applications usually specify the top-level widget returned from the GET_INFO (SCREEN, "widget") built-in procedure. A help callback occurs only when the mouse is clicked on the specified widget or any of its children widgets.

ON, 1

Confines the question mark pointer to the specified widget. If any children widgets have been moved outside the specified widget's boundaries, then the question mark pointer cannot be moved to those children unless this parameter is OFF or 0.

OFF, 0

Does not confine the question mark pointer to the specified widget.

Description

The SET (WIDGET_CONTEXT_HELP) procedure specifies the widget within which context-sensitive help interaction will occur until you click MB1 on a widget.

Example

The following example enters context-sensitive help mode; it does not restrict the question mark mouse pointer to the boundaries of the top-level DECTPU widget. This lets the pointer be moved to the application dialog boxes that have been moved outside the DECTPU boundaries.

SET (WIDGET_CONTEXT_HELP, GET_INFO (SCREEN, "widget"), OFF); 
 
      

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6020PRO_035.HTML