DEC Text Processing Utility Reference Manual

Document revision date: 30 March 2001

DEC Text Processing Utility Reference Manual

Contents

Index

Returns DECTPU's top-level widget regardless of the active DECwindows user interface. In Motif this widget is created by XtAPPCreateShell. In character-cell environments, this built-in signals the error message TPU$_REQUIRESDECW.

"width"

Returns an integer that is the current physical width of the screen.

"xui"

Returns 0. DECTPU no longer supports the XUI interface.

Return Values

array
Returns requested information about the array you specify.
integer
Returns requested information about the integer you specify.
keyword
Returns requested information about the keyword you specify.
learn_sequence
Returns requested information about the learn sequence you specify.
PRIMARY
Returns requested information about the primary global selection you specify.
program
Returns requested information about the program you specify.
SECONDARY
Returns requested information about the secondary global selection you specify.
selection_name
Returns requested information about the selection name you specify.
string
Returns requested information about the string you specify.

Description

The GET_INFO (SCREEN) procedure returns information about the screen.
For general information about using all forms of GET_INFO built-in procedures, see the description of GET_INFO.

GET_INFO (string_variable)

Format

{array |integer |keyword |program} := GET_INFO (string_variable, {"journal" |"pre_key_procedure" |"post_key_procedure" |"self_insert" |"shift_key" |"undefined_key"})

Parameters

"journal"
Returns an array that contains information about the buffer-change journal file whose name you specify with the string parameter. If the specified file is not a journal file, the integer 0 is returned.
The array indices and the contents of the corresponding elements of the returned array are as follows (all elements are of type string):

Index Contents of Element

1 Name of the buffer whose contents were journaled.

2 Date and time the journal file was created.

3 Date and time the edit session started.

4 Name of the source file. A source file is a file to which the buffer has been written. The journal file maintains a pointer to the source file. This enables the journal file to retrieve from the source file the buffer contents as they were after the last write operation. If the buffer has not been written out, or if none of the source files is available during recovery, this element contains a null string.

5 Name of the output file associated with the buffer. This is the file name specified with the SET (OUTPUT_FILE) built-in.

6 Name of the original input file associated with the buffer by the CREATE_BUFFER built-in. If there is no associated input file or if the input file is not available during a recovery, this element contains a null string.

7 Identification string for the version of DECTPU that wrote the journal file.

"pre_key_procedure"
Returns the program (stored in the specified key map or key map list) that is called before execution of code bound to keys. Returns 0 if no procedure was defined by SET (PRE_KEY_PROCEDURE).
"post_key_procedure"
Returns the program (stored in the specified key map or key map list) that is called before execution of code bound to keys. Returns 0 if no procedure was defined by SET (POST_KEY_PROCEDURE).
"self_insert"
Returns an integer (1 or 0) that indicates whether printable characters are to be inserted into the buffer if they are not defined. Use the SET (SELF_INSERT) built-in procedure to establish or change this parameter.
"shift_key"
Returns a keyword that is the key name for the key currently used as the shift key. Use the SET (SHIFT_KEY) built-in procedure to establish or change this parameter.
"undefined_key"
Returns the program that is called when an undefined character is entered. Returns 0 if the program issues the default message. Use the SET (UNDEFINED_KEY) built-in procedure to establish or change this parameter.

Index	Contents of Element
1	Name of the buffer whose contents were journaled.
2	Date and time the journal file was created.
3	Date and time the edit session started.
4	Name of the source file. A source file is a file to which the buffer has been written. The journal file maintains a pointer to the source file. This enables the journal file to retrieve from the source file the buffer contents as they were after the last write operation. If the buffer has not been written out, or if none of the source files is available during recovery, this element contains a null string.
5	Name of the output file associated with the buffer. This is the file name specified with the SET (OUTPUT_FILE) built-in.
6	Name of the original input file associated with the buffer by the CREATE_BUFFER built-in. If there is no associated input file or if the input file is not available during a recovery, this element contains a null string.
7	Identification string for the version of DECTPU that wrote the journal file.

Return Values

array
Returns requested information about the array you specify.
integer
Returns requested information about the integer you specify.
keyword
Returns requested information about the keyword you specify.
program
Returns requested information about the program you specify.

Description

The GET_INFO (string_variable) procedure returns information about the specified string. The string must be the name of a key map or key map list.
For general information about using all forms of GET_INFO built-in procedures, see the description of GET_INFO.

GET_INFO (SYSTEM)

Format

{integer |keyword |learn_sequence |program |string} := GET_INFO
(SYSTEM, {"bell" |"column_move_vertical" |"default_directory" |"display" |"enable_resize" |"facility_name" |"informational" |"journaling_frequency" |"journal_file" |"line_number" |"message_action_level" |"message_action_type" |"message_flags" |"operating_system" |"pad_overstruck_tabs" |"record_mode" |"recover" |"resize_action" |"section_file" |"shift_key" |"success" |"system_default" |"timed_message" |"timer" |"traceback" |"update" |"version" |"work_file"})

Parameters

"bell"
Returns the ALL keyword if the bell is on for all messages. Returns the BROADCAST keyword if the bell is on for broadcast messages only. Returns 0 if the SET (BELL) feature is off. Use the SET built-in procedure to establish or change this parameter.
"column_move_vertical"
Returns 1 if the MOVE_VERTICAL built-in procedure is set to keep the cursor in the same column as the cursor moves from line to line. Returns 0 if the MOVE_VERTICAL built-in preserves the offset, rather than the column position, from line to line. Use the SET (COLUMN_MOVE_VERTICAL) built-in procedure to establish or change this parameter.
"default_directory"
Returns the name of the current default directory.
"display"
Returns 1 if you have specified the /DISPLAY qualifier or if it is the default; otherwise, returns 0.
"enable_resize"
Returns 1 if resize operations are enabled; otherwise returns 0. By default, resize operations are not enabled. You can turn resizing on or off with the SET (ENABLE_RESIZE) built-in procedure.
"facility_name"
Returns a string that is the current facility name. Use the SET (FACILITY_NAME) built-in procedure to establish or change this parameter.
"informational"
Returns an integer (1 or 0) that indicates whether informational messages are displayed. Use the SET (INFORMATIONAL) built-in procedure to establish or change this parameter.
"journaling_frequency"
Returns an integer that indicates how frequently records are written to the journal file. Use the SET (JOURNALING) built-in procedure to establish or change this parameter.
"journal_file"
Returns a string that is the name of the journal file.
"line_number"
Returns an integer (1 or 0) that indicates whether DECTPU displays the line number at which an error occurred. Use the SET (LINE_NUMBER) built-in procedure to establish or change this parameter.
"message_action_level"
Returns an integer that is the completion status severity level at which DECTPU performs the message action you specify. The valid values, in ascending order of severity, are as follows: 1 (success), 3 (informational), 0 (warning), and 2 (error). Use the SET (MESSAGE_ACTION_LEVEL) built-in procedure to establish or change this parameter.
"message_action_type"
Returns a keyword describing the action to be taken when DECTPU signals an error, warning, or message whose severity level is greater than or equal to the level set with SET (MESSAGE_ACTION_LEVEL). The possible keywords are NONE, BELL, and REVERSE. Use the SET (MESSAGE_ACTION_TYPE) built-in procedure to establish or change this parameter.
"message_flags"
Returns an integer that is the current value of the message flag setting. Use the SET (MESSAGE_FLAGS) built-in procedure to establish or change this parameter.
"operating_system"
Returns a DECTPU keyword that indicates which operating system is in use. When operating on OpenVMS VAX systems, OPENVMS is returned. When operating on OpenVMS Alpha, OPENVMS_ALPHA is returned. There is no GET_INFO call to determine the type of CPU being used.
"pad_overstruck_tabs"
Returns an integer (1 or 0) that indicates whether DECTPU preserves the white space created by a tab character. Use the SET (PAD_OVERSTRUCK_TABS) built-in procedure to establish or change this parameter.
"record_mode"
Returns a keyword for the default record format and attributes for all files written from buffers having no input file. To change the default record mode for the operating system VARIABLE_CR, use the SET (RECORD_MODE, SYSTEM) built-in procedure. The possible keyword returns, and what record format and attributes they imply, are as follows:

Keyword Record Format Record Attributes

VARIABLE_NONE fab$c_var 0

VARIABLE_FTN fab$c_var fab$m_ftn

VARIABLE_CR fab$c_var fab$m_cr

STREAM fab$c_stm fab$m_cr

STREAM_LF fab$c_stmlf fab$m_cr

STREAM_CR fab$c_stmcr fab$m_cr

"recover"
Returns an integer (1 or 0) that indicates whether a recovery using a keystroke journal file is currently in progress. Be careful when using this built-in---specifying different DECTPU actions during a recovery rather than during an ordinary editing session may cause DECTPU journaling to fail.
"resize_action"
Returns the program or learn sequence designated as the application's resize action routine. Returns the UNSPECIFIED keyword if the requested resize action routine is not present. You can designate a resize action routine by using the SET (RESIZE_ACTION) built-in procedure.
"section_file"
Returns a string that is the name of the section file used when you invoked DECTPU.
"shift_key"
Returns a keyword that is the value of the current shift key set with SET (SHIFT_KEY) for the current buffer.
"success"
Returns an integer (1 or 0) that indicates whether success messages are displayed. Use the SET (SUCCESS) built-in procedure to establish or change this parameter.
"system_default"
Keyword for the operating system's default record format and attributes for all files written from buffers having no input file: VARIABLE_CR for VMS systems.
"timed_message"
Returns a string of text that DECTPU displays at 1-second intervals in the prompt area if the SET (TIMER) feature is on.
"timer"
Returns the integer 1 if SET (TIMER) has been enabled; otherwise returns 0.
"traceback"
Returns an integer (1 or 0) that indicates whether DECTPU displays the call stack for DECTPU procedures when an error occurs. Use the SET (TRACEBACK) built-in procedure to establish or change this parameter.
"update"
Returns an integer that is the update number of this version of DECTPU.
"version"
Returns an integer that is the version number of DECTPU.
"work_file"
Returns a string that is the name of the work file opened during startup.

Keyword	Record Format	Record Attributes
VARIABLE_NONE	fab$c_var	0
VARIABLE_FTN	fab$c_var	fab$m_ftn
VARIABLE_CR	fab$c_var	fab$m_cr
STREAM	fab$c_stm	fab$m_cr
STREAM_LF	fab$c_stmlf	fab$m_cr
STREAM_CR	fab$c_stmcr	fab$m_cr

Return Values

integer
Returns requested information about the integer you specify.
keyword
Returns requested information about the keyword you specify.
learn_sequence
Returns requested information about the learn sequence you specify.
program
Returns requested information about the program you specify.
string
Returns requested information about the string you specify.

Description

The GET_INFO (SYSTEM) procedure returns information about the system.
For general information about using all forms of GET_INFO built-in procedures, see the description of GET_INFO.

GET_INFO (WIDGET)

Format

{array |integer |widget |NONE} := GET_INFO (WIDGET,

{"callback_parameters", array |"children", {widget |SCREEN}, array |"menu_position", mouse_down_button |"widget_id", {parent_widget |SCREEN}, widget_name |"widget_resource_types"})

Parameters

"callback_parameters"
Returns the widget that performs the callback, the closure value associated with the widget, and the reason for the callback. In DECwindows documentation, the closure is called the tag.

array An array used to return values for the callback, the closure, and the reason. The array has the following indices of type string: "widget", "closure", and "reason_code". GET_INFO (WIDGET, "callback_parameters") places the corresponding values in the array elements. DECTPU automatically creates the array in which the return values are placed.
To use this parameter, specify a variable that has been declared or initialized before you use it. The initial type and value of the variable are unimportant. When GET_INFO (WIDGET, "callback_parameters") places the return values in the array, the initial values are lost.
The integer on the left side of the assignment operator indicates whether GET_INFO was used correctly.
GET_INFO (WIDGET, "callback_parameters") should be used in a widget callback procedure. If you use this built-in outside a widget callback procedure, the value returned is indeterminate. If you use the built-in inside a widget callback procedure and callback information is available, the built-in returns 1.
For more information about callbacks and closure values in DECwindows DECTPU, see the Guide to the DEC Text Processing Utility. For general information about using callbacks and closure values, see the VMS overview documentation.

"children"
Returns the number of widget children controlled by the specified widget. The array parameter returns the children themselves. If the SCREEN keyword is specified instead of a widget, the built-in returns the number of children controlled by the DECTPU main window widget.
"menu_position"
Returns information about any pop-up widgets that are set for menu positioning when you press the specified mouse button. If no pop-up widgets are set, returns the NONE keyword; otherwise, returns an integer-indexed array of all pop-ups set for menu positioning.

mouse_down_button This keyword (M1DOWN, M2DOWN, M3DOWN, M4DOWN, or M5DOWN) indicates the mouse button associated with the pop-up menus.

"widget_id"
Returns the widget whose name matches the specified widget name. The remaining parameters are as follows:

parent_widget The widget that is an ancestor of the widget returned by the GET_INFO (WIDGET) built-in procedure.

SCREEN A keyword indicating that DECTPU's main window widget is the ancestor of the widget that you want the GET_INFO (WIDGET) built-in procedure to return.

widget_name A string that is the fully qualified name of the widget you want the built-in to return. To specify this parameter correctly, start the string with either the name of the widget's parent, or the name of a child of the parent. If you used the SCREEN parameter instead of the parent_widget parameter, start the string with the name of a child of that widget.

Next, specify the names of the ancestors, if any, that occur in the widget hierarchy between the widget named above and the widget itself. Finally, specify the name of the widget you want the GET_INFO (WIDGET) built-in procedure to return. Separate all widget names with periods.

The fully qualified widget name is case sensitive.

"widget_resource_types"
Returns an array indexed by strings that are the widget resource data types supported by DECTPU, such as boolean or callback. Each array element is another array that is integer-indexed from 0, and contains the names of widget resources or resource types that are of the specified data type.
For more information on DECwindows concepts such as parent widgets, ancestor widgets, and the distinction between widget classes and widgets, see the VMS DECwindows Guide to Application Programming.

Return Values

array
Returns requested information about the array you specify.
integer
Returns requested information about the integer you specify.
widget
Returns requested information about the widget you specify.

Description

The GET_INFO (WIDGET) procedure returns information about DECTPU widgets in general or about a specific widget whose name you do not know at the time you use the built-in.
Use the GET_INFO (WIDGET) built-in procedure with DECwindows only.
For general information about using all forms of GET_INFO built-in procedure, see the description of GET_INFO.

Examples

The following example is a simplified version of the EVE EVE$CALLBACK_DISPATCH procedure. The original version is in SYS$EXAMPLES:EVE$MENUS.TPU. (For more information about using the files in SYS$EXAMPLES as examples, see Appendix A.)

#1
PROCEDURE eve$callback_dispatch LOCAL the_program, status, temp_array; ON_ERROR [TPU$_CONTROLC]: eve$$x_state_array {eve$$k_command_line_flag} := eve$k_invoked_by_key; eve$learn_abort; ABORT; [OTHERWISE]: eve$$x_state_array {eve$$k_command_line_flag} := eve$k_invoked_by_key; ENDON_ERROR IF NOT eve$x_decwindows_active THEN RETURN (FALSE); ENDIF; eve$$x_state_array {eve$$k_command_line_flag} := eve$k_invoked_by_menu; status := GET_INFO (WIDGET, "callback_parameters", temp_array); ! This statement using ! GET_INFO (WIDGET) ! returns the calling ! widget, the closure, ! and the reason code. ! The following statements make the contents of "temp_array" ! available to all the eve$$widget_xxx procedures eve$x_widget := temp_array {"widget"}; ! This array element contains the widget ! that called back. eve$x_widget_tag := temp_array {"closure"}; ! This array element contains the widget tag ! that is assigned to the widget in the UIL file. eve$x_widget_reason := temp_array {"reason_code"}; ! This array element contains callback reason code. ! The next statements get the callback routine from the widget arrays. loop exitif an_array = tpu$k_unspecified; ! silence if no widget matches an_array := eve$$x_widget_arrays {an_array}; the_program := an_array {eve$x_widget_tag}; if the_program <> tpu$k_unspecified then execute (the_program); eve$$found_post_filter; ! in case menu function moved cursor endif; endloop; eve$$x_state_array {eve$$k_command_line_flag} := eve$k_invoked_by_key; RETURN; ENDPROCEDURE;

PROCEDURE eve$callback_dispatch 
 
LOCAL   the_program, 
        status, 
        temp_array; 
 
ON_ERROR 
    [TPU$_CONTROLC]: 
        eve$$x_state_array {eve$$k_command_line_flag} := eve$k_invoked_by_key; 
        eve$learn_abort; 
        ABORT; 
    [OTHERWISE]: 
        eve$$x_state_array {eve$$k_command_line_flag} := eve$k_invoked_by_key; 
ENDON_ERROR 
 
IF NOT eve$x_decwindows_active 
THEN 
    RETURN (FALSE); 
ENDIF; 
 
eve$$x_state_array {eve$$k_command_line_flag} := eve$k_invoked_by_menu; 
 
 
 
status := 
   GET_INFO (WIDGET, "callback_parameters", temp_array); ! This statement using 
                                                         ! GET_INFO (WIDGET) 
                                                         ! returns the calling 
                                                         ! widget, the closure, 
                                                         ! and the reason code. 
                                                                
 
 
 
! The following statements make the contents of "temp_array" 
! available to all the eve$$widget_xxx procedures 
 
eve$x_widget := temp_array {"widget"}; 
                ! This array element contains the widget 
                ! that called back. 
eve$x_widget_tag := temp_array {"closure"}; 
                ! This array element contains the widget tag 
                ! that is assigned to the widget in the UIL file. 
eve$x_widget_reason := temp_array {"reason_code"}; 
                ! This array element contains callback reason code. 
 
! The next statements get the callback routine from the widget arrays. 
 
loop 
    exitif an_array = tpu$k_unspecified;  ! silence if no widget matches 
    an_array := eve$$x_widget_arrays {an_array}; 
    the_program := an_array {eve$x_widget_tag}; 
    if the_program <> tpu$k_unspecified 
    then 
        execute (the_program); 
        eve$$found_post_filter; ! in case menu function moved cursor 
    endif; 
endloop; 
 
eve$$x_state_array {eve$$k_command_line_flag} := eve$k_invoked_by_key; 
RETURN; 
 
ENDPROCEDURE;

This version of EVE$CALLBACK_DISPATCH handles callbacks from EVE widgets. The statement GET_INFO (WIDGET, "callback_parameters", temp_array) copies the following three items into elements of the array temp_array:

Widget that is calling back
Widget's integer closure
Reason why the widget is calling back

The array eve$$x_widget_array contains pointers to all of EVE's callback routines in elements indexed by the appropriate integer closure values. This procedure locates the correct index in the array and executes the corresponding callback routine.

Warning
This simplified version of EVE$CALLBACK_DISPATCH does not completely replace the version in existing EVE code. This example is presented solely to illustrate how EVE uses the GET_INFO (WIDGET, "callback_parameters", array) built-in procedure in a callback handling procedure.

The following example assigns to the variable the_text_widget the widget named by the string NEW_DIALOG.NEW_TEXT. The name of the parent widget, NEW_DIALOG, is optional. The returned widget is the child of the widget assigned to the variable new_dialog.

#2
the_text_widget := GET_INFO (WIDGET, "widget_id", new_dialog, "NEW_DIALOG.NEW_TEXT");

The following example shows how to use GET_INFO (WIDGET, "children") to display the entire hierarchy of widgets known to a DECTPU session:

#3
PROCEDURE eve_show_widgets ! Display the widget hierarchy local num_topmost, widget_array; widget_array := 0; num_topmost := GET_INFO (WIDGET, "children", SCREEN, widget_array); IF num_topmost > 0 THEN show_widget_tree (widget_array, ""); ENDIF; ENDPROCEDURE; PROCEDURE show_widget_tree ! Recursively display the widget tree (the_array, the_string) LOCAL child_array, highest, loop_index, num_children; child_array := 0; loop_index := 1; highest := get_info (the_array, "high_index"); LOOP EXITIF loop_index > highest; MESSAGE (the_string + GET_INFO (the_array {loop_index}, "name") + ASCII (%o11) + GET_INFO (the_array {loop_index}, "class")); num_children := GET_INFO (WIDGET, "children", the_array {loop_index}, child_array); IF num_children > 0 THEN show_widget_tree (child_array, the_string + " "); ENDIF; loop_index := loop_index + 1; ENDLOOP; ENDPROCEDURE;

PROCEDURE eve_show_widgets              ! Display the widget hierarchy 
 
local 
        num_topmost, 
        widget_array; 
 
widget_array := 0; 
num_topmost := GET_INFO (WIDGET, "children", SCREEN, widget_array); 
 
IF num_topmost > 0 
THEN 
    show_widget_tree (widget_array, ""); 
ENDIF; 
 
ENDPROCEDURE; 
 
PROCEDURE show_widget_tree      ! Recursively display the widget tree 
    (the_array, the_string) 
 
LOCAL 
        child_array, 
        highest, 
        loop_index, 
        num_children; 
 
child_array := 0; 
loop_index := 1; 
highest := get_info (the_array, "high_index"); 
LOOP 
    EXITIF loop_index > highest; 
    MESSAGE (the_string + GET_INFO (the_array {loop_index}, "name") 
             + ASCII (%o11) 
             + GET_INFO (the_array {loop_index}, "class")); 
    num_children := GET_INFO (WIDGET, "children", 
                              the_array {loop_index}, child_array); 
    IF num_children > 0 
    THEN 
        show_widget_tree (child_array, the_string + "    "); 
    ENDIF; 
    loop_index := loop_index + 1; 
ENDLOOP; 
 
ENDPROCEDURE;

Contents

Index

privacy and legal statement

6020PRO_014.HTML

parent_widget	The widget that is an ancestor of the widget returned by the GET_INFO (WIDGET) built-in procedure.
SCREEN	A keyword indicating that DECTPU's main window widget is the ancestor of the widget that you want the GET_INFO (WIDGET) built-in procedure to return.
widget_name	A string that is the fully qualified name of the widget you want the built-in to return. To specify this parameter correctly, start the string with either the name of the widget's parent, or the name of a child of the parent. If you used the SCREEN parameter instead of the parent_widget parameter, start the string with the name of a child of that widget.
	Next, specify the names of the ancestors, if any, that occur in the widget hierarchy between the widget named above and the widget itself. Finally, specify the name of the widget you want the GET_INFO (WIDGET) built-in procedure to return. Separate all widget names with periods.
	The fully qualified widget name is case sensitive.